ASDoc Generation

[atarsh]

בשבועות האחרונים לקחתי על עצמי משימה בעבודה (טוב נו, החלפתי תמורת משימה פחות מעניינת) לג'נרט דוקומנטציה עבור כל הפרויקטים שלנו.
הכלים:
* Flash Builder, כל האינטרנט
האתגר:
* כמה פרויקטים פלקסיים מול SDK 3.5
* שני פרויקטי ספריה
* עוד כמה פרויקטים ActionScript

הנסיון הראשון שלי היה עם external tools. מצאתי בכמה אתרים הסברים מפורטים ומלווים בתמונות של ההגדרות הנדרשות, ועל פרויקט הדמה שלי זה עבד מעולה. ואז עברתי לפרויקט actionscript "אמיתי".
רוב הפרויקטים שלנו משתמשים בפרויקטים אחרים כתשתיות. הבעיה הכי נפוצה ברשת היא הגדרה של ספריות קוד כאלו (למשל Cairngorm, as3corelib ושאר המצאות). בשביל זה קיים הארגומנט -external-library-path. רושמים אחריו נתיבים לכל ה-swcים של הפרויקט והכל עובד. מי אמר ששום דבר בחיים לא בא בקלות.
אז זהו... אמרנו External Tool? עכשיו אני רוצה בעזרת אותו tool לתעד פרויקט אחר. חיפוש ארוך ויסודי ברשת לא העלה אף אפשרות סבירה להתייחס לכל ה-referenced libraries ביחד. אם מישהו מכיר דרך כזו – אני אשמח לשמוע.

בשלב הזה עברתי לבחון אופציה נוספת – שימוש ב-ant.
אחרי הרבה חפירות ברשת הצלחתי להוריד ולהתקין ant (לא תאמינו כמה הסברים מלווים בתמונות יש להתקנה על Flex Builder, לעומתם הסברים ל-Flash Builder מצאתי... אחד, כאן. ההבדלים מינוריים אבל מרגיזים).
המשך החפירות הניב סקריפט אנט שמייצר את הדוקומנטציה:

Syntax: [ Download ] [ Hide ]

Syntax: [ Download ] [ Show ]

Using xml Syntax Highlighting

<project name="asdoc" default="main" basedir="./">
        <target name="main" depends="clean,compile" description="full build of asdocs"/>
        <target name="clean">
                <delete includeemptydirs="true">
                <fileset dir="docs/asdoc" includes="**/*"/>
                </delete>
        </target>
        <target name="compile" depends="clean">
                <mkdir dir="docs/asdoc"/>
                <exec executable="C:\Program Files\Adobe\Adobe Flash Builder 4\sdks\4.0.0\bin\asdoc.exe" failonerror="true">
                        <arg line='-source-path src'/>
                        <arg line='-doc-sources src'/>
                        <arg line='-external-library-path ./libs ../as3corelib/bin ../Cairngorm/bin '/>
                        <arg line='-main-title "My App Documentation"' />
                        <arg line='-window-title "My App Documentation"' />
                        <arg line='-output docs/asdoc' />
                </exec>
        </target>
</project>

Parsed in 0.005 seconds, using GeSHi 1.0.8.4

(זו הגרסה האחרונה – פירוט בהמשך)
למעשה מה שיש כאן זו הגדרה של שלוש משימות: האחרונה מג'נרטת את הדוקומנטציה, השניה מוחקת גרסה קודמת והראשונה מריצה את שתי האחרות אחת אחרי השניה. הקשיים שלי מתרכזים במשימה שנקראת compile, שהיא ההפעלה של ה-asdoc tool.
יש לציין ששימוש בסקריפט ant כזה לא פותר את עניין ה-reuse שבגללו עזבתי את ה-external tool, אבל מכיוון שככה הסקריפט עבור כל פרויקט יושב תחת הפרויקט עצמו זה מעט יותר הגיוני בעיני.
חשוב להבין שמה שעושה כלי ה-asdoc שבא עם Flex זה בעצם לקמפל את הפרויקט, וחשוב עוד יותר לדעת שהוא לא עושה את זה עם mxmlc אלא הוא בעצמו קומפיילר. הוא תומך ברוב הארגומנטים של mxmlc אבל לא בכולם, ויש עוד כמה הבדלים.
הפרויקטים הראשונים שעבדתי עליהם היו פרויקטים ActionScript, כלומר אינם תלויים בגרסת ה-Flex SDK. זה אפשר לי לעבוד עם ה-asdoc tool של SDK4 שהוא גאון יחסית לזה של SDK3.5. בגדול – כל נסיון להפעיל את הכלי של SDK3.5 התנפץ על השורה המתסכלת Error: '' is not a directory.
וואלה? ומאיפה הבאת את '', שבאמת לא נשמע כמו תיקיה – אבל.. מה?
אחרי ימים ארוכים של חיפושים החלטתי להוריד את SDK3.5 מהרשת ולנסות את מזלי. הגרסה האחרונה ברשת היתה מאותו build כמו שהיה לי. לא הייתי מאוד אופטימית בקשר למהלך הזה אבל נו – אם וודו אז וודו.
מה אתם יודעים – זה עבד.
אז הצלחתי לקמפל פרויקטים ActionScriptיים מול הכלי של SDK3.5 והמצב נראה טוב. השלב הבא – פרויקט ספריה.


פרויקט ספריה לא נשמע כמו משהו שאמור להיות מסובך, אבל מסתבר שיש כמה בורות שאפשר ליפול אליהם.
אם אתם מהאנשים שדוגלים בגישת ה"לא למחוק, לקמנט" והמקבילה הקומפילטיבית שלה "לא למחוק, להוריד מהקומפילציה" – כאן זה מתנקם בכם.
רואים את השורה -doc-sources src בסקריפט לעיל? היא אומרת לasdoc tool לרוץ על כל הקבצים תחת התיקיה src ולג'נרט דוקומנטציה לכולם. כמובן שאם יש לכם קלאסים שלא מתקמפלים כי אף אחד לא משתמש בהם כבר 15 שנה והצ'קבוקס שלהם תחת Flex Library Build Path / Classes לא מסומן עכשיו תצטרכו להעיף אותם אחד אחד.
יש אופציה של exclude-classes שמקבלת רשימה של קלאסים שאין צורך לתעד, אבל היא לא עובדת יחד עם doc-sources. היא עובדת עם doc-classes – פרמטר שמקבל רשימה של קלאסים שצריך לקמפל, במקום תיקיה. אז עכשיו צריך רשימה של כל הקלאסים שאנחנו רוצים לקמפל, וזה בטח הרבה יותר פשוט מאשר רשימה של כל הקלאסים שאנחנו לא רוצים לקמפל.. או משהו.
הדרך הקצרה להשיג את הרשימה הזו היא מתוך הקובץ .FlexLibProperties . קצת מניפולציות על התוכן ואפשר להשיג רשימה, שכמובן תפסיק להיות רלוונטית ברגע שמישהו יוסיף קלאס לספריה. שימו לב שבניגוד להוספת הקלאס ל-swc (שכנראה שלא תצליחו להמשיך לעבוד בלי לבצע), הוספת המחלקה להגדרת הקומפילציה תהיה silent failure שכנראה שלא תגלו עד שיבוא לקוח כועס לצעוק. רוצה אומרת- לא פתרון יציב כל כך, אבל הי – זה מה יש.

הלאה: ייצור fat swc. למי שלא מכיר את המונח, הכוונה היא ל-swc שכולל את התיעוד של הקוד שיש בו, כך שמעבר עכבר מעל לשם פונקציה (או משתנה, או מחלקה) יציג את התיעוד הרלוונטי. כאן אנחנו מגלים את ההבדל העיקרי בין הכלים של SDK3.5 ו- 4: זה של 3.5 פשוט לא יודע לעשות את זה.
עם 4 זה ממש פשוט, בפקודת הג'נרציה מבקשים ממנו שלא למחוק את הxmlים שנוצרים בתהליך ואז מעתיקים אותם לתוך ה-swc (שהוא "סתם" קובץ zip, זוכרים?) וכמובן שאפשר להגיד ל-ant לעשות את זה בשבילכם.
אבל עם SDK3.5? קדחת. לא שמדובר בפעולה מאוד מסובכת, זה פשוט לא נראה אפשרי. בתור התחלה, הפקודה שאומרת לכלי שלא למחוק את קבצי הביניים לא קיימת עבור 3.5. אני בכלל לא בטוחה שאותם קבצים נוצרים, קיבלתי את הרושם שהתהליך שונה. אם קיוויתם שיש לי פתרון אז לא, אבל אם למישהו אחר יש פתרון אני אשמח לשמוע.

האתגר הבא: svn data. אנחנו עובדים עם svn כ- source control, והוא נוהג להשאיר קבצים מוסתרים עם מידע שלו בתוך כל תיקיה שהוא מנטר. זוכרים את השורה שמוחקת את הגרסה הקודמת של asdoc ומכינה את המקום לגרסה החדשה? במקור היא מחקה את התיקיה כולה ויצרה אותה מחדש. svn לא אהב את זה כלכך, והסתבכתי עם svn conflicts שמי שכתב את subclipse לא תכנן בכלל. נאלצתי להתקין tortoise כדי לצמצם את הנזק, והבנתי שצריך פתרון אחר למחיקת הקבצים.
אז מסתבר שמי שכתב את ant דווקא כן חשב על svn, ובהגדרת המחיקה בעזרת fileset אפשר להגיד לו שלא ימחק קבצים מתוך רשימה מוגדרת. התיקיה .svn שמחזיקה את המידע של ה-source control נמצאת ברשימה הזו. תענוג. הגרסה המובאת במאמר זה לא מוחקת svn data.

מה נשאר לנו? פרויקטים פלקסיים (Flex Application). גם כאן האפשרות לשימוש ב-doc-classes עוזרת הרבה, בגלל אותם קבצי legacy שלא נמחקו כי למישהו כואב לזרוק דברים שהוא אסף. גם במקרה הזה נסיון לתעד כל מה שתחת src גורם בעיות מאותו סוג כמו פרויקט ספריה, אבל כאן אין את flexLibProperties להעתיק ממנו את רשימת המחלקות לקומפילציה.
doc-classes נותן פתרון הולם: מעבירים לו רק את המחלקה העיקרית של האפליקציה. הוא מנסה לקמפל כל מה שהוא נתקל בו (ורק מה שהוא נתקל בו) וכך אנחנו מקבלים משהו שיותר דומה לדרך העבודה של mxmlc, ולא מנסים לקמפל מחלקות שאינן בשימוש.

זו החוויה שלי עם יצירת דוקומנטציה.
אם חסכתי למישהו 3 דקות של קללות חסרות-טעם או 20 דקות גוגלינג עשיתי את שלי.