הוספת מטא נתונים לתיעוד שלך
אספקת תיעוד טוב היא משימה חיונית לכל מפתח. זה לא רק עוזר לעמיתים שלך להבין במהירות את ההגיון ואולי את תהליך המחשבה שלך, אלא זה גם עוזר לך להיכנס לקוד מהר יותר למקרה שתחזור אליו לאחר מספר חודשים.
לכן חשבתי ליצור רשימה (לא שלמה) של תגים מיוחדים לשימוש עם JSDoc-comments. אלה הם אלה שאני אישית משתמש לעתים קרובות ביותר והוכחו כמספקים יתרון אמיתי.
מנה ראשונה בסיסית
דוגמא הקוד הבאה מציגה דוגמה פשוטה ובסיסית שיש להשתמש בה עבור כל תיעוד. הוא מציין את המטרה, הפרמטרים וכן את סוג ההחזרה.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
קוד לדוגמה בתיעוד
אתה יכול לספק דוגמה אמיתית של קוד מוטבע עם התג "@example" כדי להבהיר מקרי שימוש מסוימים. ניתן להשתמש בתג זה גם כדי להציג במהירות מקרי קצה אפשריים בתרחיש אמיתי.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
חבר באיזה מודול
השתמש בתג "@memberOf" כדי להגדיר איזה מודול או משתנה אב מארח את הקוד המתועד.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
הערת קישור
אתה יכול להשתמש בתג "@see" יחד עם התג "@link" כדי לספק תיעוד כתובת URL בפורמט נכון, במקום להדביק כמה כתובות אתרים בתוך התיעוד הראשי.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
תיעוד סוג גנרי
אם הקוד שלך משתמש בסוגים גנריים, אתה יכול להשתמש בתג "@template" כדי להגדיר את שם הסוג הגנרי. שם זה משמש אז בתגיות "@param" הנפוצות כהפניה לסוג.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
הגדרת המחבר של קטע קוד
במקרים מסוימים, חשוב לציין גם את המחבר. ניתן לבצע זאת בפשטות באמצעות התג "@author". אתה יכול לא רק לספק את שמך, אלא גם דוא"ל בתור אסמכתא ליצירת קשר.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
קוד שהוצא משימוש
אין הרבה מה לספר על התג "@deprecated", מכיוון שהוא עושה בדיוק את מה שהיית מצפה. תג זה נמצא בשימוש נפוץ בממשקי API והוא יכול גם להתייחס לקוד החדש.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
גִרְסָה
השתמש בתג "@version" כדי לתעד גרסה עבור הקוד הנתון. שימו לב שהתג הזה לא מתייחס לגרסת האפליקציה, אלא באמת לגרסת האפליקציה שלו. תוספת של גרסה זו פירושה שהקוד הספציפי הזה השתנה.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
ממתי הקוד זמין לשימוש
אתה יכול להשתמש בתג "@since" כדי לתעד מאיזה מספר גרסה הקוד הבא נוסף ל-API הציבורי. חשוב לציין כאן הוא שהגרסה מתייחסת כעת להיקף היישום. זה מנוגד לתג "@version" מלפני כן, אשר מוקף לגוש הקוד הספציפי שהוא מתעד.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
