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

4.5. תיעוד ה-packages

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

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

התוכן של קובץ זה הוא למעשה הערה גדולה אחת הכתובה בפורמט HTML. אין צורך לסמן את הקובץ בעזרת /** ו-*/.

להלן תוכנו של 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 אחרים.