שפת Java - חלק ראשון

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

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

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

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

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

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

@author author name

משמשת לציון שמו של כותב ה-class/interface.

ניתן לשלב מספר תגיות @author בתוך אותה הערת javadoc.

@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 אז יש לציין “No replacement”.

{@link}

תגית זו באה לציין קישור למקור אחר.

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

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

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