Javadoc

עד כה הכרנו שני סוגים של הערות:
  • הערות קצרות - בדרך כלל נמצאות בתוך הקוד.
  1. // This is a short comment
  • בלוק הערה - מאפשר לכתוב הערות ארוכות יותר בצורה נוחה.
  1. /*
  2.  * Simple comment block
  3.  */

כעת נכיר דרך נוספת לתיעוד הקוד - Javadoc.

Javadoc

ג'אווה מאפשרת שיטה נוספת של תיעוד - Javadoc.
כתיבה של תיעוד כזה דומה מאוד לבלוק ההערה שכבר ראינו קודם, עם "*" אחת נוספת:
  1. /**
  2.  * Javadoc comment block
  3.  */

בשביל מה אנחנו צריכים את זה?

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

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

כיצד משתמשים ב- Javadoc?

Javadoc מאפשר שימוש בתגים. תג משמש לסימון חלק מיוחד שיופיע בצורה שונה בדפי ההסבר החיצוניים. קיים מגוון של תגים שונים, כאשר המשותף לכולם הוא סימון של "@" בתחילתם. נפרט כאן חלק מהם. (שימו לב: בתחילת כל שורה של ההערה ישנה *)

תיאור מחלקה

בראש כל מחלקה יש לשים בלוק Javadoc הכולל תיאור של המחלקה. תיאור המחלקה חשוב מאוד; התגים המפורטים כאן למטה - פחות.
  • תג ה-@author מציין מיהו כותב הקוד.
  • תג ה-@version מציין מה גירסת התוכנית.

דוגמא:
  1. /**
  2.  * This class represents a complex number.
  3.  * Every complex number can be written in the form a + bi, 
  4.  * where a and b are real numbers called the real part and 
  5.  * the imaginary part of the complex number, respectively.
  6.  *
  7.  * @author John Doe
  8.  * @version 0.99
  9.  */
  10. public class Complex {
  11.       ...
  12. }

תיאור שיטה

בראש כל שיטה ציבורית (public), יש לשים בלוק Javadoc הכולל תיאור של השיטה. כאן תפקיד התגים חשוב מאוד.
  • תג ה-@param מתאר את הפרמטרים אותם מקבלת השיטה. יש לכתוב את שם המשתנה, ואז את תיאורו. על כל משתנה - יש לשים תג param. אין צורך לציין טיפוס - הכלי האוטומטי מסוגל לזהות זאת בעצמו. עם זאת, חשוב להקפיד על כתיבה נכונה של שמות המשתנים.
  • תג ה-@return מתאר מה השיטה מחזירה. כאן אין צורך לכתוב את שם המשתנה, מספיק לכתוב את תיאורו.
  • גם התגים @author ו-@version ניתנים לשימוש כאן, אך הם בדרך כלל פחות רלוונטיים.

דוגמא:
  1. /**
  2.  * This function increments the value of the Complex object
  3.  * by the value of the given Complex.
  4.  *
  5.  * @param other The Complex number that we increase the current complex by
  6.  * @return true if the addition was successful, false otherwise
  7.  */
  8. public boolean add(Complex other) {
  9.       ...
  10. }

תיאור שדה

גם לפני משתנים ציבוריים (public) בעלי משמעות ומשתנים סטאטיים רצוי לשים בלוק קצר של Javadoc שיסביר עליהם, לדוגמה:
  1. /**
  2.  * Maximum speed of a car
  3.  */
  4. public static final int MAX_SPEED = 210;

תגים נוספים

  • תג ה-@see מפנה למקורות נוספים, שיטות או משתנים קשורים, וכדומה.
  • תג ה-@link מפנה למקורות נוספים כלליים (כתובת כלשהי באינטרנט).

מנגנון ה-Javadoc הוא מוכוון HTML. ניתן לשלב תגי HTML בבלוק הערות כזה.

אז מה זה עוזר לנו?

כעת אנו יכולים לקחת כלי שניתן ע"י Java, להריץ אותו על הקוד עם ההערות שכתבנו, ונקבל דפי הסבר חיצוניים לקוד שלנו. דוגמאות לכך ניתן לראות ב- String API, Math API. בשתי הדוגמאות ניתן לראות הסבר שכתבו על המחלקות String ו- Math, כולל הסבר על השדות והשיטות שלהן.

כאשר נריץ את כלי ה- Javadoc על הקוד שלנו, גם נקבל דפי html כמו בדוגמאות, עם התיעוד שכתבנו למחלקות שלנו.

איך להוציא זאת כפלט כאשר משתמשים ב- command?

  1. הפעילו וכנסו לחלון ה- command.
  2. כנסו לתיקייה בה נמצאים קבצי קוד ה- java שלכם.
  3. הריצו את הפקודה הבאה אשר תיצור את ה- javadoc עבור כל קבצי ה- java ותשים אותם בתיקייה "doc":
    1. javadoc -version -private -d doc *.java
  4. אם הפקודה הקודמת הסתיימה בהצלחה, נוספה לכם תיקייה בשם doc ובה אתם צריכים לפתוח את הקובץ בשם "index.html" (בד"כ דאבל-קליק על הקובץ יפתח את הדפדפן עם המידע).

איך להוציא זאת כפלט בעזרת אקליפס?

http://www.eclipse-blog.org/eclipse-ide/generating-javadoc-in-eclipse-ide.html