תכנות מתקדם ב-Java/תיעוד

אם הגעתם עד הלום, קרוב לוודאי שאתם כבר מכירים היטב את מושג התיעוד. בפרק זה נראה דרך מתקדמת יותר של תיעוד אותה מציעה ג'אווה.

צורת כתיבה

תזכורת

עד כה הכרנו שני סוגים של הערות:

• הערות קצרות - בדרך כלל נמצאות בתוך הקוד.

// This is a short comment

• בלוק הערה - מאפשר לכתוב הערות ארוכות יותר בצורה נוחה.

/*
* Simple comment block
*/

דרך נוספת - Javadoc

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

/**
* Javadoc comment block
*/

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

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

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

שימוש וסימנים נפוצים

Javadoc מאפשר שימוש בתגים. קיים מגוון של תגים שונים, כאשר המשותף לכולם הוא סימון של "@" בתחילתם. נפרט כאן חלק מהם.

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

דוגמה:

/**
* This class does nothing useful
* @author Somebody
* @version 0.99
*/
public MyClass {
...
}

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

דוגמה:

/**
* This function calculates something
* @param num1 The first number
* @param num2 The second number
* @return What we get from those two numbers
*/
public int myFunc(int num1, int num2) {
...
}

• גם לפני משתנים ציבוריים בעלי משמעות רצוי לשים בלוק קצר של Javadoc שיסביר עליהם, לדוגמה:

/**
* Right direction
*/
public static final int RIGHT = 1;

תגים נוספים

Tag & Parameter	Usage	Applies to	Since
@author name	Describes an author.	Class, Interface, Enum
@version version	Provides software version entry. Max one per Class or Interface.	Class, Interface, Enum
@since since-text	Describes when this functionality has first existed.	Class, Interface, Enum, Field, Method
@see reference	Provides a link to other element of documentation.	Class, Interface, Enum, Field, Method
@param name description	Describes a method parameter.	Method
@return description	Describes the return value.	Method
@exception classname description @throws classname description	Describes an exception that may be thrown from this method.	Method
@deprecated description	Describes an outdated method.	Method
{@inheritDoc}	Copies the description from the overridden method.	Overriding Method	1.4.0
{@link reference}	Link to other symbol.	Class, Interface, Enum, Field, Method
{@value}	Return the value of a static field.	Static Field	1.4.0

יצירת תיעוד בעזרת הכלי האוטומטי

כדי ליצור תיעוד אוטומטי, כתבו בשורת הפקודה (ובתיקייה בה נמצאים הקבצים להם תרצו ליצור תיעוד. בדוגמה זו file1.java ו-file2.java): javadoc file1.java file2.java אפשר ליצור תיעוד עבור כל הקבצים בתיקייה באמצעות "*" (בדיוק כמו עם ההידור): javadoc *.java כברירת מחדל, התיעוד נוצר בספרייה בה נמצאים קבצי התוכנית. כדי ליצור את התיעוד בספרייה אחרת, השתמשו בדגל -d ואחריו כתבו את הספרייה הרצוייה, למשל: javadoc -d ./Documentation *.java הוצגו כאן רק חלק קטן מהאפשרויות. קיימות אפשרויות נוספות רבות. למעוניינים, ראו הסברים נוספים באתר חברת סאן.

אם אתם עובדים בסביבת העבודה eclipse, תוכלו לעשות זאת מתוך התפריטים: בתפריט Project בחרו Generate Javadoc... ושם בחרו את ההגדרות הנוחות לכם.

פלט ואזהרות

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

הפרק הקודם: עבודה לפי ממשק

תיעוד

הפרק הבא: בנאים