נספח א':

Writing Comments for the javadoc tool

כתיבת הערות מסוג javadoc

· הקדמה

· אופן כתיבתה של הערת javadoc

· אופן הפעלתה של תכנית ה-javadoc

· סגנון הערת ה-javadoc

· התגיות שקיימות ב-javadoc

· תיעוד ה-packages

· תיעוד המחלקות האנונימיות

· אפשרויות נוספות

הקדמה

כאשר יוצרים את קבוצת מסמכי ה-HTML אשר נקראת API Documentation באמצעות תכנית השירות, javadoc, הערות הטקסט אשר משולבות במסמכי ה-HTML שנוצרים מגיעים מן המקורות הבאים:

1. קבצי קוד המקור של ה-classes וה-interface אשר הוגדרו. הערות (הערות מסוג javadoc) אשר יופיעו בצמידות למשתנים, המתודות והמתודות הבונות ישולבו במסמכי ה-HTML אשר ייווצרו.
2. קבצי הערות לתיאור של כל אחד ואחד מן ה-packages שיש בפרוייקט.
3. קובץ הערות לתיאור כללי של כל קבוצת ה-packages שיש בפרוייקט.
4. קבצים שונים אחרים (קבצי תמונות, דוגמאות קוד מקור וכל דבר אחר אשר רוצים לשלב אליו קישור במסמכי ה-HTML שנוצרים).

כדאי לציין כי נספח זה מבוסס על ההנחיות שמפרסמת Sun בכל הקשור ליצירת documentation.

אופן כתיבתה של הערת javadoc

צורתה הכללית של הערת javadoc אשר תשולב במסמכי ה-documentation (מסמכי ה-HTML) שיווצרו היא **/ בהתחלה ו- /* בסוף. כל הערת javadoc נחלקת לשניים: בתחילתה מופיע טקסט ובהמשך נכתבות תגיות ה-java doc. בין שני החלקים (הטקסט המתאר והתגיות) תופיע שורה ריקה שבתחילתה *.

/**

* This is the descriptive text of the doc comment.

*
* @Xxx Comment for the tag.
* @Yyy Comment for the tag.

*/

public class Aaa()
}

}

הערת ה-javadoc חייבת להופיע בצמידות מעל הגדרתה של מתודה/משתנה/מחלקה וכו'... וללא כל שורת ריווח ביניהם.

בהערות הדוקומנטציה אשר משולבות במסמך יש להימנע מלשלב את תגיות ה-heading שקיימות ב-HTML (<H1>, <H2> וכו'...). שילובן עלול לפגוע באופן פעולתה של תכנית ה-javadoc.

הלוכסן בתחילת הערת ה-javadoc יהיה באותה עמודה שבה מתחיל הקוד. כך, למשל, ניתן לראות בדוגמא כי הלוכסן אשר מתחיל את ההערה נמצא בדיוק מעל האות p. תחילת הערת ה-javadoc תהיה סימן ההתחלה **/ וסופה של הערת ה-javadoc יהיה הסימן */. גם בשורת ההתחלה וגם בשורת הסיום, מלבד סימני ההתחלה: /** ו- */ לא יופיע דבר.

כל שורה נוספת אשר תופיע בהערת ה-javadoc תתחיל בסימן * (בין אם היא ריקה ובין אם לאו). יש להקפיד על כך שכל הכוכביות יהיו בדיוק אחת מעל השניה. ריווח בודד יפריד בין כל כוכבית אשר מופיעה בתחילת השורה לטקסט שבהמשך.

בין ההערה הטקסטואלית לתגיות תופיע שורת ריווח (גם בתחילתה תופיע כוכבית).

שורות של יותר מ-80 תווים יש לשבור למספר שורות קצרות יותר. אם תוכנה הטקסטואלי של ההערה נחלק למספר פסקאות אז יש להפריד ביניהן באמצעות תגית ה-HTML, <P>, אשר משמשת להפרדה בין פסקאות.

המשפט הראשון בכל הערת javadoc צריך להיות משפט קצר אשר מהווה תיאור קצר ומדויק של הפריט שאליו ההערה מתייחסת. על משפט ההתחלה להיות מנוסח באופן שניתן יהיה להבינו גם מבלי לקרוא את יתר המשפטים. המשפט הראשון יופיע בחלק ה-summary, התיאור התמציתי שיש לכל פריט ופריט (לכל field, method, class , package וכו'..). משפט ההתחלה מסתיים עם הנקודה הראשונה שאחריה ריווח (או ריווח tab או סוף שורה). אם מעונינים בכך שהנקודה הראשונה לא תהווה את סיומו של המשפט הקצר אז יש לדאוג שלא יהיה אחריה ריווח (וגם לא ריווח טאב וגם לא סימן של סוף שורה). אם בכל זאת אמור להיות אחריה ריווח ניתן למקם במקום ריווח רגיל ריווח קשיח (&nbsp). להסברים נוספים בנוגע לריווח קשיח ניתן לפנות לספרי: "המדריך הישראלי ל-HTML 4.0". כך, למשל, בהערה הבאה, משפט הקיצור לא יסתיים במילה "Dr.". משפט הקיצור יסתיים במילה resteraunt.

/**

* This class describes Dr.&nbspShakshuka resteraunt.

*/

כאשר יש מספר מתודות שהן overloaded versions חשוב שההסבר הקצר שיש לכל אחת ואחת מהן יכלול תיאור של מה שמייחד כל אחת מהן מן האחרות.

בכתיבת הערות ה-javadoc יש להימנע מלהתייחס לפלטפורמה מסוימת (אלא אם כן, יש צורך להתייחס לפלטפורמות שונות כדי להבטיח שהשימוש שיעשה במחלקה המתוארת אכן ירוץ בכל פלטפורמה).

ההערות צריכות להיות מלאות, ועליהן לכלול גם את תחומי הערכים המותרים לפרמטרים השונים, התייחסות למקרים פינתיים ותנאים נוספים.

כאשר ההערות לא מכסות סוגיה מסוימת או שהן מאפשרות ליישמה באופן שונה בפלטפורמות שונות יש לציין זאת.

כאשר רוצים לציין משהו שהוא ספציפי לפלטפורמה מסוימת יש להתחיל את המשפט ב- "On <platform>". לדוגמא:

“On Linux systems, the behavior of the method is. .. “

לחילופין, ניתן להקדים את המשפטים אשר מתייחסים לפלטפורמות שונות במשפט: "Implementation-Specific:".

קיימים מצבים שבהם ה-javadoc משלב הערות באופן עצמאי. הכרת מקרים אלה יכולה לחסוך בקידוד מיותר:

כאשר במחלקה שמגדירים, מתודה דורסת מתודה אחרת שמגיעה בהורשה ממחלקה אחרת אז ה-javadoc tool ישלב בהערות שהוא ייצר עבור המתודה הדורסת את המשפט: “Overrides” עם קישור לדוקומנטציה של המתודה שנדרסה (במחלקה המורישה).

כאשר ב-interface שמגדירים, מתודה דורסת מתודה אחרת שמגיעה בהורשה מ-interface אחר אז ה-javadoc tool ישלב בהערות שהוא ייצר עבור המתודה הדורסת את המשפט: “Overrides” עם קישור לדוקומנטציה של המתודה שנדרסה (ב-interface שמוריש).

כאשר במחלקה שמגדירים, מתודה דורסת מתודה אחרת שמגיעה מ-interface אשר מיושם אז ה-javadoc tool ישלב בהערות שהוא ייצר עבור המתודה הדורסת את המשפט: “Specified by” עם קישור למתודה (כפי שהוגדרה ב-interface).

בכל אחד משלושת המקרים שנסקרו, אם המתודה אשר הוגדרה לא לוותה בהערות עבור ה-javadoc אז ה-javadoc tool יצרף אליהן את ההערות שניתנו למתודה הנדרסת (כפי שנכתבו במחלקה המורישה או ב-interface המיושם). מסיבה זו, אם ההערות שנכתבו ב-interface המיושם או במחלקה המורישה מספקות אז לא כדאי להוסיף הערות נוספות. אם תתווסף הערה נוספת אז יוצמד אליה קישור להערות של המתודה הנדרסת בצירוף המשפט “specified by” או “overrides” (בהתאם לנסיבות).

אופן הפעלתה של תכנית ה-javadoc

את תכנית ה-javadoc מפעילים בשורת הפקודה באופן הבא:

javadoc [options] [package | source.java]

כלומר,

מייד לאחר שכותבים בשורת הפקודה “javadoc” יש לרשום את שם (או שמות) ה-package (או ה-packages) שעבורם יווצרו מסמכי HTML (בתור API Documentation). מסמכי ה-HTML שיווצרו כוללים (בברירת המחדל שלהם) תיעוד של המרכיבים שהרשאת הגישה שלהם היא public או protected בלבד. מסמכים אלה כוללים מסמך תיעוד לכל מחלקה ומסמך תיעוד לכל package. בנוסף, תכנת ה-javadoc גם יוצרת מסמך HTML אשר מתאר את היררכית המחלקות אשר נוצרת (tree.html) ומערך מסמכי HTML אשר מהווה index לכל האלמנטים אשר תועדו.

ה-options שניתן לשלב לפני שמו/שמם של קובץ קוד המקור/קבצי קוד המקור (או שמו/שמם של ה-package\packages) הם:

-public

מסמכי ה-HTML יכללו תיעוד של מחלקות ורכיבי מחלקות שהרשאות הגישה שלהם היא public בלבד.

-protected

מסמכי ה-HTML יכללו תיעוד של מחלקות ורכיבי מחלקות שהרשאות הגישה שלהם הן public או protected.

-package

מסמכי ה-HTML יכללו תיעוד של מחלקות ורכיבי מחלקות שהרשאות הגישה שלהם הן public, protected או package friendly בלבד.

-private

מסמכי ה-HTML יכללו תיעוד של כל המחלקות ורכיבי המחלקות הקיימים.

-encoding name

כדי לציין את ה-encoding שמשמש בכתיבת ההערות שמופיעות בקובץ קוד המקור. בדרך כלל, כיוון שאת ההערות כותבים באנגלית וזוהי ברירת המחדל אין כל צורך להשתמש באפשרות זו.

-docencoding name

כדי לציין את ה-encoding שישמש בכתיבת מסמכי ה-HTML אשר ייוצרו.

-version

כדי שמסמכי ה-HTML יכללו את תוצאותיהן של התגיות @version יש להשתמש באפשרות זו. בברירת המחדל תגיות אלה לא נלקחות בחשבון בעת יצירת מסמכי ה-HTML.

-author

כדי שמסמכי ה-HTML יכללו את תוצאותיהן של התגיות @author יש להשתמש באפשרות זו. בברירת המחדל תגיות אלה לא נלקחות בחשבון בעת יצירת מסמכי ה-HTML.

-noindex

כדי שהתיעוד שיווצר לא יכלול את מסמך ה-index.html אשר סוקר את ה-packages הקיימים בפרויקט.

-notree

כדי שמסמך היררכית ההורשה אשר הקישור אליו מופיע בתיעוד של כל מחלקה וכל interface לא ייווצר.

-d directory

כדי לקבוע את הספרייה שבה יישמרו מסמכי ה-HTML אשר ייווצרו.

-verbose

באמצעות ציונה של אפשרות זו, בעת יצירת מסמכי ה-HTML על ידי javadoc יופיעו על צג המחשב נתונים נוספים (בנוסף לאלה אשר תמיד מופיעים) אשר מתארים את מספר אלפיות השניה שערכו יצירתם של מסמכי ה-HTML עבור כל אחד מקבצי קוד המקור.

-sourcepath path

באמצעות אפשרות זו ניתן לציין את ה-path למיקום שבו נמצאת ספרית ה-package העליונה ביותר בהיררכית הספריות אשר מייצגות את ה-packages השונים (אם ה-javadoc מופעל כדי לייצור תיעוד לפרוייקט כולו) או את ה-path למיקום שבו נמצאים קבצי ה-source code המסוימים שאותם רוצים לתעד בהערות javadoc. בדרך כלל אין כל צורך להשתמש באפשרות זו כיוון שנהוג להפעיל את javadoc בספריה שבה נמצאת הספרייה אשר מייצגת את ה-package העיקרי (ה-package שבראש היררכית ההורשה).

-classpath path

באמצעות אפשרות זו ניתן לציין את מקומם של קבצי ה-java byte code אשר משמשים את תכנית ה-javadoc בפעולתה. כאשר משתמשים באפשרות זו המיקום שיצוין הוא גם המיקום שבו תכנית ה-javadoc תחפש את קבצי ה-source code שעבורם תכנית ה-javadoc מייצרת את מסמכי ה-HTML. אפשרות זו דורסת, למעשה, את ערכו של משתנה הסביבה (אם נקבע): classpath ולכן כדאי לקבוע את ערכה כשווה לאוסף כל ה-path הרלוונטיים (עם ; כסימן מפריד ביניהם). דוגמה לאופן השימוש בתכונה זו: javadoc -classpath .;c:\jDir;c:\win\javaClasses thePackage.ClassName. ערך ברירת המחדל של ה-classpath כאשר מפעילים את תכנית ה-javadoc הוא ה-Path לספריה הנוכחית + ערכו של classpath, משתנה הסביבה.

-nodeprecated

באמצעות אפשרות זו גורמים לכך שמסמכי ה-HTML שנוצרים לא יכללו בתוכם את ההערות שסומנו בתגית @deprecated.

סגנון כתיבתה של הערת ה-javadoc

כאשר משלבים בתוך הערת ה-javadoc שמות (של מחלקות,packages, interfaces, מתודות, משתנים, ארגומנטים ודוגמאות של קוד) או מלים שמורות אז יש לסמנם באמצעות התגיות <code> ו- </code>. לדוגמא:

/**

* This class is an improved version of the <code>Button</code> class.

*
* . . .
*

*/

ניתן לשלב בתוך הערת javadoc קישור למסמך אחר אשר מתאר מחלקה אחרת באמצעות @link. יש להימנע מקישור (באמצעות @link) של כל אחד משמות המחלקות אשר מופיעים בהערות ה-javadoc אל המסמך המתאר את אותה מחלקה. שימוש מוגזם ב-@link עלול לגרום לכך שההערות ייראו מסורבלות וקשות להבנה. יש להשתמש ב-@link רק באותם מקומות שבהם יש מקום להניח שמי שיקרא את ההערות (יקרא את תיעוד ה-HTML שיווצר) עשוי יהיה לרצות במידע נוסף ולכן יהיה מעוניין בקישור שיוכל להפעיל. כמו כן, אין מקום, באותה הערת javadoc, לחזור על אותו קישור יותר מפעם אחת. די ביצירת הקישור הראשון.

כאשר מתייחסים בהערת דוקומנטציה כתובה למתודה מסוימת אשר הוגדרה במספר גרסאות (overriding method) יש לציין בתוך הסוגריים העגולות שיופיעו אחרי שם המתודה את הטיפוסים (עם פסיקים ביניהם) ובכך יהיה ברור לאיזו גרסה של אותה מתודה מתכוונים. כך למשל, אם המתודה doSomething הוגדרה בשתי גרסאות: האחת בעלת פרמטר אחד מטיפוס int והשניה בעלת שני פרמטרים מטיפוס float אז ההבחנה ביניהם תיעשה באופן הבא: doSomething(int) ו- doSomething(float,float). אם מתכוונים לכל הגרסאות של המתודה doSomething אז יש לכתוב את שמה ללא כל סוגריים (כדי שלא יהיה בלבול ויחשבו שמתכוונים לגרסה שלא מקבלת אף ארגומנט). כדי שיהיה ברור שמדובר במתודה יש להוסיף לפני שמה את המילה method.

המשפט הראשון בכל הערת javadoc איננו חייב להיות משפט. הוא יכול להיות גם ביטוי או צירוף של מספר קטן של מלים שאיננו מהווה משפט אך דיו כדי להסביר. בדרך זו ניתן, לעתים, לקבל בהירות גבוהה יותר. הדבר תקף בייחוד בנוגע לתגית @param.

דוגמא:

/**

* Requests that this applet be resized.

*

* @param width The new requested width for the applet

*/

כאשר מנסחים את משפטי ההסבר שניתנים בתוך הערות הדוקומנטציה יש להשתמש בגוף שלישי. כך למשל, יש לרשום “Gets the first name” בהסבר על מתודה נתונה (במקום לרשום “Get the first name”).

בהסבר שנותנים לפעולתה של מתודה אין צורך לשלב “The method gets the first name”. ניתן ישירות לרשום את מה שהמתודה עושה: “Gets the first name”.

גם בהסברים שנותנים למחלקה,שדה ו-interface אין צורך לציין את הנושא (אין צורך לרשום “The class is ...” או “The field describes ...” או “The interface describes...”). יש לרשום ישירות את העיקר בלבד. כך, למשל, במקום לרשום הסבר כגון “The field is a button label” יש לרשום “A button label”.

כאשר בהסבר שכותבים מתכוונים לאובייקט הנוכחי שנוצר מהמחלקה ושעליו המתודה הנתונה פועלת יש להשתמש ב-this במקום ב-the ! כך, למשל, בהסבר למתודה getParent שהוגדרה במחלקה Component נרשום את ההסבר: “Gets the parent of this component” במקום “Gets the parent of the component”.

כאשר כותבים הסבר יש לכתוב הסבר אשר יוסיף מידע מעבר למידע אשר ניתן להסיק ללא כל קושי משם המתודה/המשתנה/המחלקה אשר מוסברים. יש להימנע ממתן הסבר אשר חוזר, למעשה, על מה שניתן להסיק ללא כל קושי משמה של המתודה/המשתנה/המחלקה. כך, למשל, בהסבר הבא למתודה setText, חזרה על כל אחת מן המלים אשר מופיעות בשמה של המתודה מיותרת לחלוטין.

/**

* Sets the text in this text field.

*

* @param text The text of the text field.

*/

public synchronized void setText(String text)

{

. . .

}

לחילופין, ניתן היה לכתוב את ההסבר הבא:

**/

* Sets the text that is presented by this

* text component to be the specified text.

* @param t the new text.

* If this parameter is <code>null</code> then

* the text is set to the empty string .

* @see java.awt.TextComponent#getText

*/

public synchronized void setText(String t)

{

…

}

כאשר משתמשים במילה field יש להיזהר מיצירת בלבול. המילה field יכולה לתאר מספר דברים שונים. היא יכולה לתאר text field, instance variable ואפילו static variable. כדי להימנע מבלבולים כגון אלה יש לציין במדויק למה מתכוונים. כך, למשל, אם מתכוונים לשדה טקסט יש לרשום text field.

יש להימנע משימוש בראשי תיבות. כך למשל יש לרשום “for example” במקום “e.g.”.

התגיות שקיימות ב- javadoc

בתוך הערות ה-javadoc ניתן, כפי שהוצג, לשלב תגיות בעלות משמעות מיוחדת בתוצאה הסופית של פעולת תכנית ה-javadoc. תגיות אלה מתחילות בסימן @ וניתן למקמן בתחילת השורה בלבד. אם משלבים את אותה תגית מספר פעמים בתוך אותה הערת javadoc אז יש למקם את התגיות הללו בקבוצה אחת. כך, למשל, אם התגית @author מופיעה יותר מפעם אחת בתוך אותה הערה אז יש לרשום את כל השורות האמורות יחדיו (אחת מתחת לשניה). בדרך זו, תכנית ה-javadoc תתייחס אל קבוצת התגיות הזהות באופן מיוחד.

את תגיות ה-javadoc ניתן לחלק לשלוש קבוצות:

קבוצת התגיות שניתן לשלב בהערות javadoc אשר נכתבות לצורך יצירת תיעוד של field:

בתוך הערת javadoc אשר מוצמדת ל-field ניתן לכלול את התגיות הבאות: @see, @since ו- @deprecated בלבד.

קבוצת התגיות שניתן לשלב בהערות javadoc אשר נכתבות לצורך יצירת תיעוד של class או interface:

@author author name

לציון שמו של כותב ה-class/interface. ניתן לשלב מספר תגיות @author בתוך אותה הערת javadoc. אם המחבר איננו ידוע אז הארגומנט שתגית זו תקבל יהיה “unascribed”.

@version version number

לציון מספר הגרסה (בדרך כלל של ה-JDK). בכל הערת javadoc שנכתבה לצורך יצירת תיעוד של class או interface ניתן לשלב תגית @version אחת לכל היותר.

@see className

ליצירת קישור שלחיצה עליו תוביל לתיעוד של class, interface, method או field מסוימים. קיימות מספר אפשרויות בעת הפעלת תגית זו:

ניתן להפנות לתיעוד של field או method (בשם שצוין) אשר שייכים לאותה מחלקה:

@see # nameOfMethodOrField

ניתן להפנות לתיעוד של field או method (בשם שצוין) אשר שייכים למחלקה אחרת:

@see nameOfOtherClass#nameOfMethodOrField

ניתן להפנות לתיעוד של method מסוים מתוך מספר מתודות בעלות שם זהה (overriding methods) אם מציינים בתוך סוגריים אשר באים אחרי שמה של המתודה את הטיפוס/הטיפוסים של הפרמטר/הפרמטרים שלה.

@see java.awt.Container#add(String,Component)

ניתן לשלב בתוך הערת javadoc של class\interface יותר מתגית @see אחת.

@since sinceText

באמצעות תגית זו מציינים כי ה-field\method\constructor\class או interface נתמכים החל מגרסת JDK מסוימת.

@deprecated deprecatedText

תגית זו באה לציין כי ה-class או ה-interface המתועדים נחשבים ל- deprecated, ולכן יש להימנע מלהשתמש בהם. ההערה שנהוג למקם אחרי התגית הזו היא הפניה למתודה/מחלקה שבהם יש להשתמש במקום. אם אין כל תחליף למרכיב שהוכרז כ-deprecated אז לשלוח לתגית “No replacement”.

קבוצת התגיות שניתן לשלב בהערות javadoc אשר נכתבות לצורך יצירת תיעוד ל-method או constructor:

@param parameterNameDescription

כדי לתת הסבר לפרמטר של ה-method או של ה-constructor. דוגמא: @param size long size of the file. אחרי התגית @param יש לציין תחילה את שמה של התגית ורק אחריו הסבר קצר. המילה הראשונה בהסבר תהא הטיפוס של אותו פרמט, ולכן מקובל להקדימה ב-“a”, “an” או “the”. דוגמא: @param num the int number to be tested. את הטיפוס יש לרשום באותיות קטנות (שיהיה ברור שלא מדובר בשמה של מחלקה אלא באובייקט). ה-javadoc יוסיף את תגיות ה-CODE סביב שמו של הפרמטר באופן אוטומטי (סביב הארגומנט הראשון שישלח לתגית @param). משפט ההסבר שיופיע אחרי שמו של הפרמטר לא יסתיים בנקודה, יתחיל באות קטנה ויהיה ביטוי/אוסף מלים שאיננו מהווה משפט מלא. מסיבה זו, ההסבר יתחיל באות קטנה.

@return description

כדי לתת הסבר לערך המוחזר על ידי ה-method. דוגמא: @return length of the fileבמתודות שמחזירות void וב-construcotrs אין להשתמש בתגית זו.

@exception fulltQualifidClassNameDescription

כדי לתת הסבר לטיפוס ה-exception אשר עלול להיזרק. התוצאה לשימוש בתגית זו היא הופעת Throws: במסמך ה-HTML אשר ייוצר ובו רשימת סוגי ה-exception אשר עלולים להיזרק מן המתודה. כל סוג של exception יופיע כקישור למסמך ה-javadoc אשר מתאר אותו (את מחלקת ה-exception המתאימה). דוגמא: @exception IOException if the file is too big

התגית @throws זהה בפעולתה לתגית @exception. יש לתעד כל exception שצוין ב-throws או exception שיש סבירות גבוהה להניח שהמתכנת ירצה לנסות לתפוס אותו (למעט errors ו-NullPointerException).

@see className

תגית זו, שהוסברה לעיל, גורמת להוספת “See Also” מתאים. תגית זו ניתן להפעיל במספר אופנים (ראה מעלה).

@since sinceText

ראה את ההסבר שכבר הוצג. התגית @since תופיע רק בהסבר אשר ניתן ל-class/interface. אין לכלול את התגיות @since בהסברים שניתנים למרכיבי ה-class/interface אלא אם הם הוספו מאוחר יותר בגרסה יותר מאוחרת של אותה class/interface.

@deprecated deprecatedText

לציון method\constructor מיושנים (deprecate). מייד לאחר התגית יש לספק הסבר שהמשפט הראשון שבו יאמר מתי זה נהיה deprecated ולאחריו מהו התחליף שבו יש להשתמש. המשפטים שיבואו אחר כך יכולים לכלול הסברים למה זה נהיה deprecated. כאשר מסבירים מהו התחליף יש להשתמש בתגית @link כדי שיופיע קישור למיקום שבו מופיע התיעוד של התחליף.
דוגמא: @deprecated As of JDK1.4, replaced by {@link setXxxx()}
אם אין כל תחליף למה שנקבע כ-deprecated אז יש לציין “No replacement”.

@serial

@serialData

@serialField

אלה שלוש תגיות חדשות (הופיעו ב-jdk1.2) והן באות לציין משתנים אשר יעברו serialization. משתנים אלה חייבים להיות מסוג instance variables כיוון ש-static variables ו-transient variables לא עוברים serialization.

{@link}

תגית זו באה לציין קישור למקור אחר. להלן דוגמא לשימוש בתגית זו בתוך קובץ קוד המקור של המחלקה Applet:

/**

* Returns an absolute URL naming the directory of the document in which

* the applet is embedded. For example, suppose an applet is contained

* within the document:

* <blockquote><pre>

* http://java.sun.com/products/jdk/1.2/index.html

* </pre></blockquote>

* The document base is:

* <blockquote><pre>

* http://java.sun.com/products/jdk/1.2/

* </pre></blockquote>

*

* @return the {@link java.net.URL} of the document that contains this

* applet.

* @see java.applet.Applet#getCodeBase()

*/

public URL getDocumentBase() {

return stub.getDocumentBase();

}

יצירת תיעוד ל- Default Constructor:

כדי לתעד default constructor יש להגדירו מפורשות מחדש ולשלב בהגדרה שלו את ההערות שבהן מעונינים.

סדר כתיבת התגיות:

את התגיות יש לרשום בסדר הבא:

@author
@version
@param
@return
@exception
@see
@since
@serial
@deprecated

כדי לקבל תיעוד יותר קריא מומלץ לחלק את התגיות לקבוצות. כך, למשל, את התגיות @author ו-@version ניתן למקם בקבוצה אחת ואת יתר התגיות בקבוצה שניה. כאשר רושמים את אותה תגית מספר פעמים יש לראות באוסף התגיות הזהות אשר מתקבל קבוצת תגיות אשר תופרד מיתר התגיות שלפניהן באמצעות שורה ריקה.

את תגיות ה-@param יש למקם כקבוצת תגיות נפרדת (שורת ריווח לפניה) וכל אחת מהן תתאר את הפרמטרים של ה-metho/constructor על פי סדר הופעתם.

את תגיות ה-@author יש למקם כקבוצת תגיות נפרדת (שורת ריווח לפניה) וכל אחת מהן תתאר את אחד מכותבי ה-class / constructor על פי הסדר הכרונולוגי. יוצר המחלקה (הראשון) יופיע ראשון.

את תגיות ה-@exception יש למקם כקבוצת תגיות נפרדת (שורת ריווח לפניה) וכל אחת מהן תתאר exception אחר אשר עלול להיזרק. תגיות ה-exceptions יופיעו על פי שמות ה-exceptions (לפ סדר האלף-בית).

את תגיות ה-@see יש למקם כקבוצת תגיות נפרדת (שורת ריווח לפניה). סדר הופעתן צריך להיות – במידת האפשר – כמידת הקירבה של הקישור. כאשר יש קישורים למספר מתודות זהות (overriding methods) יש לציין תחילה את הקישור לגרסה חסרת הפרמטרים ולבסוף את הקישור לגרסת שיש לה את מספר הפרמטרים הרב ביותר.

את תגית ה-@param יש לציין לכל פרמטר (גם כאשר התיעוד שלו ברור מאיליו).

את תגית ה-@return יש לציין בכל מקרה. גם כאשר ההסבר ברור מאיליו.

תיעוד ה-packages

כדי לתעד את ה-packages יש ליצור את המסמך package.html, לשמור אותו בתיקיה שבה שמורים קבצי קוד המקור (*.java). בכל תיקיית קבצי קוד מקור ששייכים ל-package מסוים יש לרשום את המסמך package.html אשר מתעד את אותו package מסוים.

המסמך package.html אשר יישמר בכל תיקיה של package יכלול הערות אשר יתווספו לתקציר המחלקות וה-interfaces . תחילה יופיע תקציר המחלקות וה-interfaces ורק אחריו יופיע תוכנו של המסמך package.html (כל מה שמופיע בתוך מרכיב ה- BODY שבתוכו). תוכנו של package.html צריך לכלול תיאור של השירותים שאותו package מספק, את הקשרים שיש בין המחלקות וה-interfacesc אשר מרכיבים אותו ואף קישורים למסמכי תיעוד נוספים חיצוניים לAPI documentation.

להלן תוכנו של package.html:

בתחילה:

יופיע החלק “Package Xxx Description”. חלק זה יתחיל במשפט סיכום קצר אשר מציין מה ה-package מספק. למשל, “Provides classes and interfaces for handling mobile communication".”. אחריו יש לספק תיאור יותר מפורט.

בהמשך:

יש לספק את ה-package specification: תיאורים וקישורים לאינפורמציה רלוונטית אחרת.

אחר כך:

יש לספק Related Documentation: קישורים למסמכים אחרים (דוגמאות, מדריכים וכו').

כאשר ניתן יהיה להשתמש בתגית @category אז יופיע חלק נוסף:

תיאור לוגי של קבוצות ה-classes וה-interfaces שיש ב-package זה. כמו כן, קישורים ל-packages, classes ו-interfaces אחרים.

תיעוד המחלקות האנונימיות

ה-javadoc tool לא יוצר תיעוד עבור המחלקות הפנימיות האנונימיות. אם רוצים לתעד מחלקה פנימית אנונימית אז להוסיף את תיאורה למתודה או למחלקה החיצונית.

אפשרויות נוספות

ניתן לעשות שימוש בקבצי תמונה. הסברים נוספים ניתן למצוא ב-http://java.sun.com/j2se/javadoc/writingdoccomments/#packagecomments. את קבצי התמונה (כמו גם קבצים נוספים) יש למקם בתת ספריה בשם doc-files אשר תישמר בתיקיה שבה נמצאים קבצי ה-source code. תיקיה זו תועתק לתיקיית מסמכי ה-api documentation אשר ייוצרו.

ניתן ליצור קובץ בשם overview.html ולשמור אותו בתיקיה שבה קבצי קוד המקור. תוכנו של קובץ זה יילקח וישולב ב-overview שניתן לקבל כאשר בוחרים ב-overview (במסמכי ה-API documentation אשר נוצרים).

באמצעות יצירת doclet ניתן לקבוע פורמט אחר להערות ה-documentation אשר ייוצרו. הסברים נוספים ניתן למצוא ב-http://java.sun.com/j2se/javadoc/writingdoccomments/#packagecomments.

2000 © All the rights reserved to

Haim Michael & Zindell Publishing House Ltd.

No parts of the contents of this paper may be reproduced or transmitted

in any form by any means without the written permission of the publisher !

This book can be used for personal use only !!!

Brought to you by

ZINDELL

http://www.zindell.com

לנוחיותך, להלן תוכן העניינים של הספר:

פרק 1: ההתחלה Let's start -

פרק 2: הבסיס Basic -

פרק 3: מחלקות Classes -
פרק 4: מערכים ומחרוזות תוויםArrays & Strings -
פרק 5: הורשהInheritance -
פרק 6: ניתוח מרכיביה של מחלקהReflection -
פרק 7: מחלקות פנימיותInner Classes -
פרק 8: יישומוניםApplets -
פרק 9: תכנות מקביליThreads -

פרק 10: ממשק משתמש גרפי בסיסי Graphic User Interface using AWT -

פרק 11: הטיפול באירועים Events Handling -

פרק 12: הטיפול בשגיאות Exceptions Handling -

פרק 13: פעולות קלט/פלט I\O Streams -
פרק 14: תקשורתNetworking -

פרק 15: ממשק משתמש גרפי מתקדם Graphic User Interface using SWING -
פרק 16: מבני נתונים Data Structures -

פרק 17: מחלקות מוכנות לתיאור מבני נתונים Collections API -

פרק 18: קישור לבסיס נתונים - JDBC

פרק 19: הפעלת מתודות מרחוק RMI -

פרק 20: הסבת התכנית למדינות אחרותInternationalization -

פרק 21: שילוב קוד בC- Native Methods (JNI) -

פרק 22: שימוש בXML-

פרק 23: אבטחת מידע Security -

פרק 24: גרפיקה דו ממדית 2D Graphics -

פרק 25: ניהול הזיכרון Memory Management -

נספחים:

נספח א': אופן הפעלת ה-javadoc

נספח ב': הכרות ראשונית עם UML

נספח ג': הכרות ראשונית עם Design Patterns

נספח ד': שיפור הביצועים של התכנית

נספח ה': כללי תחביר בכתיבת קוד מקור

נספח ו': פקודות שכיחות ב-SQL