כיצד לתעד קוד JavaScript באמצעות JSDoc

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

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

עבור מפתחי JavaScript, JSDoc היא דרך טובה להתחיל לתעד את הקוד שלך.

מה זה JSDoc?

תיעוד קוד יכול להיות מורכב ומייגע. עם זאת, יותר אנשים מזהים את היתרונות של גישת "מסמכים כקוד"., ולשפות רבות יש ספריות שעוזרות להפוך את התהליך לאוטומטי. לתיעוד פשוט, ברור ותמציתי. בדיוק כמו ה לשפת Go יש GoDoc כדי להפוך תיעוד מקוד לאוטומטי, אז ל-JavaScript יש JSDoc.

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

זה שומר את התיעוד בתוך הקוד, כך שכאשר אתה מעדכן את הקוד שלך, קל לעדכן את התיעוד.

הגדרת JSDoc

היוצרים של JSDoc הקלו להתחיל ולהגדיר את JSDoc בפרויקט ה-JavaScript שלך.

כדי להתקין JSDoc באופן מקומי, הפעל:

npm install --save-dev jsdoc

זה יתקין את הספרייה בפרויקט שלך כתלות במפתחים.

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

לדוגמה:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

ה @param ו @החזרות תגיות הן שתיים ממילות המפתח המיוחדות הרבות שבהן תומך JSDoc כדי להסביר את הקוד שלך.

כדי ליצור את התיעוד עבור קוד זה, הפעל npx jsdoc ואחריו הנתיב לקובץ ה-JavaScript שלך.

לדוגמה:

npx jsdoc src/main.js

jsdoc path/to/file.js

פקודה זו תיצור an הַחוּצָה תיקייה בשורש הפרויקט שלך. בתוך התיקיה, תמצא קבצי HTML המייצגים את דפי התיעוד שלך.

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

הגדרת פלט JSDoc

אתה יכול ליצור קובץ תצורה כדי לשנות את התנהגות ברירת המחדל של JSDoc.

לשם כך, צור א conf.js קובץ וייצא מודול JavaScript בתוך קובץ זה.

לדוגמה:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

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

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

השתמש בפקודה זו כדי להפעיל את JSDoc עם קובץ תצורה:

jsdoc -c /path/to/conf.js

כדי להקל על הפעלת הפקודה הזו, הוסף אותה בתור א תסריטים כניסה בתוך שלך package.json קוֹבֶץ:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

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

דוגמה לתיעוד שנוצר עם JSDoc

להלן ספריית חשבון פשוטה עם לְהוֹסִיף ו להחסיר שיטות.

זוהי דוגמה לקוד JavaScript מתועד היטב:

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },
/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

הערות JSDoc מספקות תיאור ברור ומקיף של הספרייה ושיטותיה, כולל:

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

ההערות כוללות גם את @module תג כדי לציין שהקובץ הזה הוא מודול וה- @דוגמא תג כדי לספק דוגמה לקוד עבור כל שיטה.

תיעוד קוד מפתחים בדרך הנכונה

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

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