מבוא לג'אדוק

1. סקירה כללית

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

למרבה המזל, כל הגרסאות המודרניות של ה- JDK מספקות את הכלי Javadoc - ליצירת תיעוד API מתגובות הנמצאות בקוד המקור.

תנאים מוקדמים:

  1. JDK 1.4 (JDK 7+ מומלץ לגירסה האחרונה של תוסף Maven Javadoc)
  2. הג'וינט /פַּח התיקיה שנוספה נָתִיב משתנה הסביבה
  3. (אופציונלי) IDE עם כלים מובנים

2. הערות Javadoc

נתחיל בתגובות.

מבנה התגובות של Javadoc נראה דומה מאוד לתגובה רגילה עם מספר שורות, אך ההבדל העיקרי הוא הכוכבית הנוספת בהתחלה:

// זוהי תגובה בשורה אחת / * * זוהי תגובה רב-שורתית רגילה * / / ** * זוהי Javadoc * /

הערות בסגנון Javadoc עשויות להכיל גם תגי HTML.

2.1. פורמט Javadoc

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

הערות אלה מורכבות בדרך כלל משני חלקים:

  1. התיאור של מה שאנחנו מגיבים עליו
  2. תגי החסימה העצמאים (מסומנים בתווית "@סמל) המתארים מטא-נתונים ספציפיים

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

2.2. Javadoc ברמת הכיתה

בואו נסתכל איך תיראה תגובת Javadoc בכיתה:

/ ** * גיבור הוא היישות העיקרית אליה נשתמש. . . * * אנא עיין במחלקה {@link com.baeldung.javadoc.Person} לגבי זהות אמיתית * @ מחבר קפטן אמריקה * * / class public SuperHero extends Person {// שדות ושיטות}

יש לנו תיאור קצר ושני תגי בלוק שונים - עצמאי ומובנה:

  • תגים עצמאיים מופיעים אחרי התיאור עם התג כמילה הראשונה בשורה, למשל @מְחַבֵּר תָג
  • תגים מוטבעים עשויים להופיע בכל מקום ומוקפים בסוגריים מסולסלים, למשל @קישור תג בתיאור

בדוגמה שלנו, אנו יכולים גם לראות שני סוגים של תגי חסימה המשמשים:

  • {@קישור} מספק קישור מוטבע לחלק שהוזכר בקוד המקור שלנו
  • @מְחַבֵּר שם הכותב שהוסיף את הכיתה, השיטה או השדה שעליו מגיבים

2.3. Javadoc ברמת השדה

אנחנו יכולים גם להשתמש בתיאור ללא תגי חסימה כאלה בתוך שלנו גיבור על מעמד:

/ ** * השם הציבורי של גיבור שהוא דבר שכיח * / פרטי String heroName;

שדות פרטיים לא יופקו עבורם Javadoc אלא אם כן נעביר את ה- -פְּרָטִי אפשרות לפקודת Javadoc.

2.4. Javadoc ברמת השיטה

השיטות יכולות להכיל מגוון תגי חסימה של Javadoc.

בואו נסתכל על שיטה בה אנו משתמשים:

/** * 

זהו תיאור פשוט של השיטה. . . * סופרמן! *

* @ פארם נכנס פגע בכמות הנזק הנכנס * @ החזר את כמות גיבור הבריאות לאחר ההתקפה * @ ראה HERO-402 * @ מאז 1.0 * / ציבורי int בהצלחה Attacked (int incomingDamage) {// האם הדברים מחזירים 0; }

ה הותקף בהצלחה השיטה מכילה תיאור ותגיות חסימות עצמאיות רבות.

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

בוא נעבור על התגיות שאנו נתקלים בדוגמה לעיל:

  • @ פאראם מספק כל תיאור שימושי לגבי פרמטר או קלט של שיטה שהיא מצפה לה
  • @לַחֲזוֹר מספק תיאור של מה שיטה תחזיר או תוכל
  • @לִרְאוֹת תיצור קישור דומה ל- {@קישור} תג, אבל יותר בהקשר של הפניה ולא מוטבע
  • @מאז מציין איזו גרסה המחלקה, השדה או השיטה נוספו לפרויקט
  • @גִרְסָה מציין את גרסת התוכנה, הנפוצה עם פקודות מאקרו% I% ו-% G%
  • @ זורק משמש להסבר נוסף על המקרים שהתוכנה מצפה לחריג
  • @ מיושן נותן הסבר מדוע קוד הוצא משימוש, מתי ייתכן שהוצא משימוש ומהן החלופות

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

3. דור ה- Javadoc

על מנת ליצור את דפי ה- Javadoc שלנו, נרצה להעיף מבט בכלי שורת הפקודה הנשלח עם ה- JDK, ובתוסף Maven.

3.1. כלי שורת הפקודה Javadoc

כלי שורת הפקודה Javadoc הוא חזק מאוד אך יש בו מורכבות מסוימת.

הפעלת הפקודה javadoc ללא אפשרויות או פרמטרים יביא לשגיאה ולפרמטרי פלט שהוא מצפה.

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

בואו נפתח שורת פקודה וננווט לספריית הפרויקט.

בהנחה שהשיעורים כולם ב src תיקייה בספריית הפרויקט:

[מוגן בדוא"ל]: ~ $ javadoc -d doc src \ *

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

שימוש ב- IDE עם הפונקציונליות המובנית הוא כמובן קל יותר ומומלץ בדרך כלל.

3.2. Javadoc עם תוסף Maven

אנו יכולים גם להשתמש בתוסף Maven Javadoc:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0 1.8 1.8 ... 

בספריית הבסיס של הפרויקט, אנו מפעילים את הפקודה ליצור את ה- Javadocs שלנו לספרייה באתר target:

[מוגן בדוא"ל]: ~ $ mvn javadoc: javadoc

תוסף Maven חזק מאוד ומאפשר יצירת מסמכים מורכבים בצורה חלקה.

בואו נראה עכשיו איך נראה דף Javadoc שנוצר:

אנו יכולים לראות נוף עץ של הכיתות שלנו גיבור על הכיתה מתרחבת. אנו יכולים לראות את התיאור, השדות והשיטה שלנו, ואנחנו יכולים ללחוץ על קישורים למידע נוסף.

תצוגה מפורטת של השיטה שלנו נראית כך:

3.3. תגיות Javadoc מותאמות אישית

בנוסף לשימוש בתגי חסימה שהוגדרו מראש לעיצוב התיעוד שלנו, אנו יכולים גם ליצור תגי חסימה מותאמים אישית.

על מנת לעשות זאת, עלינו רק לכלול א -תָג אפשרות לשורת הפקודה Javadoc שלנו בפורמט ::.

על מנת ליצור תג מותאם אישית שנקרא @מקום מותר בכל מקום, המוצג בכותרת "מיקומים בולטים" במסמך שנוצר, עלינו להריץ:

[דוא"ל מוגן]: ~ $ javadoc - מיקום תג: a: "מיקומים בולטים:" -d doc src \ *

על מנת להשתמש בתג זה, אנו יכולים להוסיף אותו למקטע החסימה של הערת Javadoc:

/ ** * זו דוגמה ... * @ מיקום ניו יורק * @ חוזר בלה בלה * /

התוסף Maven Javadoc גמיש מספיק כדי לאפשר גם הגדרות של התגים המותאמים אישית שלנו pom.xml.

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

... מיקום מקומות ראויים לציון: ...

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

4. מסקנה

מדריך מבוא מהיר זה כיסה כיצד לכתוב Javadocs וליצור אותם באמצעות שורת הפקודה Javadoc.

דרך קלה יותר להפיק את התיעוד הייתה להשתמש בכל אפשרויות IDE מובנות או לכלול את התוסף Maven לתוך שלנו pom.xml הקובץ והפעל את הפקודות המתאימות.

דוגמאות הקוד, כמו תמיד, ניתן למצוא באתר GitHub.