תעד את קוד ה-Java שלך באופן אוטומטי עם Javadoc

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

Java מספקת בנוחות פתרון מובנה לבעיה: Javadoc.

Javadoc יכול לעזור לך לתעד את הקוד שלך באופן אוטומטי

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

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

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

מה זה בדיוק Javadoc ואיך זה עובד?

Javadoc היא תוכנית עצמאית שמגיעה יחד עם מהדורות ערכת הפיתוח של Java (JDK) של אורקל. למעשה, אתה לא יכול להוריד אותו בנפרד. כאשר אתה מוריד ו

התקן את אחת מגרסאות ה-JDK של אורקל, הוא גם יתקין את Javadoc.

כאשר אתה מפעיל אותו, Javadoc מייצר תיעוד HTML מהערות בפורמט מיוחד בקוד המקור של Java שלך. תהליך זה יוצר תיעוד שימושי וקריא יותר תוך עידוד שיטות עבודה מומלצות.

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

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

הערות Javadoc צריכות להקדים מיד הצהרת מחלקה, שדה, בנאי או מתודה. ההערה עצמה צריכה:

• התחל עם שלוש הדמויות /**.
• כלול כוכבית בתחילת כל שורה חדשה.
• סגור עם שתי הדמויות */.

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

הנה דוגמה להמחשת הערות פשוטות של Javadoc המתארות פונקציה שמקבלת תמונה מכתובת URL ומדפיסה אותה למסך. ההערה מקדימה מיד את הפונקציה ומתארת ​​מה היא עושה. בלוק הערות זה עושה שימוש גם בשלושה תגים ספציפיים לקטע: @param, @לַחֲזוֹר, ו @לִרְאוֹת.

/**
* מחזירה אובייקט תמונה שניתן לצבוע אותו על המסך.
* הארגומנט url חייב לציין אבסולוט {@קישור כתובת URL}. השם
* ארגומנט הוא מפרט שהוא יחסי לארגומנט url.
* 

* שיטה זו תמיד חוזרת מיד, בין אם ה
*תמונה קיימת. מתי זֶה יישומון מנסה לצייר את התמונה
* המסך, הנתונים ייטענו. הפרימיטיבים הגרפיים
* שמציירים את התמונה יצבעו בהדרגה על המסך.
*
* @param url כתובת URL מוחלטת המספקת את מיקום הבסיס של התמונה
* @param שם את המיקום של התמונה, ביחס לארגומנט url
* @לַחֲזוֹר התמונה בכתובת ה-URL שצוינה
* @לִרְאוֹת תמונה
*/
פּוּמְבֵּי תמונה getImage(כתובת אתר, שם מחרוזת){
לְנַסוֹת {
לַחֲזוֹר getImage(חָדָשׁ URL(כתובת אתר, שם));
 } לתפוס (MalformedURLEexception ה) {
לַחֲזוֹרריק;
 }
}

כאשר Javadoc מעבד את הקוד שלמעלה, הוא יוצר דף אינטרנט הדומה לדף הבא:

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

התגיות @בשימוש בסוף ההערה מייצרות את פרמטרים, החזרות, ו ראה גם קטעים שאתה רואה.

כדאי לעקוב אחר ה @param תג עם שם הפרמטר, רווח ותיאור שלו. במקרה שלמעלה, ישנם שני פרמטרים: כתובת אתר ו שֵׁם. שימו לב ששניהם מופיעים תחת אותה כותרת פרמטרים בפלט התיעוד. אתה יכול לרשום כמה פרמטרים הדרושים עבור הפונקציה או השיטה שאתה מתאר.

ה @לַחֲזוֹר תג מתעד את הערך שהפונקציה מחזירה, אם בכלל. זה יכול להיות תיאור פשוט של מילה אחת או משפטים רבים, בהתאם לנסיבות.

ה @לִרְאוֹת תג מאפשר לך לתייג פונקציות אחרות הקשורות או רלוונטיות. במקרה זה, התג @see מתייחס לפונקציה אחרת שנקראת פשוט Image. שים לב שהפניות שנעשו עם תג זה הן קישורים הניתנים ללחיצה, המאפשרים לקורא לקפוץ לפריט שאליו יש הפניה ב-HTML הסופי.

יש עוד תגים זמינים כגון @version, @author, @exception ואחרים. בשימוש נכון, התגים עוזרים לקשר פריטים זה לזה ומאפשרים לנווט בתיעוד בקלות.

הפעלת Javadoc בקוד המקור שלך

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

javadoc --עֶזרָה

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

javadoc ~/code/שם קובץ.java
javadoc ~/code/*.java

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

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

זהו התיעוד עבור מחלקה אחת וקצרה של Java כדי להדגים את הפלט. הכותרת מציגה את שם המחלקה וכן את השיטות הכלולות בתוכה. גלילה מטה חושפת הגדרות מפורטות יותר של כל אחת משיטות הכיתה.

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

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

8 בלוגי Java הטובים ביותר למתכנתים

קרא הבא