Beispielcode für die Dokumentation mit JSDoc

Einführung

JSDoc Es handelt sich um ein Open-Source-Tool zur Generierung von API-Dokumentation in JavaScript. Es ermöglicht Entwicklern, ihren Code mithilfe von Kommentaren zu dokumentieren.

Beispielcode für die Dokumentation mit JSDoc

Nachfolgend ein Beispiel für die Dokumentation einer Methode:

/**
* یک فایل را بر اساس شناسه بازیابی می‌کند.
* @param {string} id شناسه فایل.
* @returns {File} شی فایل.
*/
const getFileById = (id) => {
// کد...
}

Installieren Sie JSDoc

Sie können JSDoc global verwenden mit npm Installieren:

npm install -g jsdoc

Oder installieren Sie die Installation für ein bestimmtes Projekt wie folgt:

npm install --save-dev jsdoc

Wie man JSDoc verwendet

Dokumentation hinzufügen

Um mit der Dokumentation Ihres Codes zu beginnen, fügen Sie einfach einen Kommentar hinzu mit /** Fügen Sie am Anfang jedes Codeblocks (Module, Methoden, Klassen, Funktionen usw.) Folgendes hinzu:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
*/
const getByEmail = async (email) => {
// کد...
}

Sie können auch JSDoc-Tags verwenden, um weitere Informationen hinzuzufügen:

/**
* کاربر را با استفاده از ایمیل بازیابی می‌کند.
* @async
* @method
* @param {String} email - ایمیل کاربر
* @returns {User} شی کاربر
* @throws {NotFoundError} اگر کاربر پیدا نشود.
*/
const getByEmail = async (email) => {
// کد...
}

Dokumentationserstellung

Nach dem Hinzufügen von Kommentaren können Sie die Dokumentation als Webseite generieren, indem Sie einfach den folgenden Befehl ausführen:

jsdoc path/to/my/file.js

Erweiterte Tipps

Verwendung der Konfigurationsdatei

Wenn Ihr Projekt groß ist und viele Dateien und Ordner enthält, können Sie das Verhalten von JSDoc mithilfe einer Konfigurationsdatei anpassen:

{
"source": {
"includePattern": ".+\\.js(doc|x)?$", // فقط فایل‌های با پسوند .js، .jsdoc یا .jsx پردازش شوند.
"include": ["."], // تمام پوشه‌ها بررسی شوند.
"exclude": ["node_modules"] // پوشه node_modules نادیده گرفته شود.
},
"opts": {
"destination": "./docs/", // مقصد تولید مستندات.
"recurse": true // پوشه‌ها به صورت بازگشتی بررسی شوند.
}
}

Unterstützung in VSCode

Der VSCode-Editor unterstützt JSDoc standardmäßig und bietet Funktionen wie die automatische Vervollständigung von Kommentarstrukturen und die Anzeige von Funktionsinformationen.

Verwenden Sie eine benutzerdefinierte Vorlage

Sie können das Standard-JSDoc-Format überschreiben, indem Sie eine Datei erstellen. layout.tmpl Passen Sie die Einstellungen an und legen Sie die Werte in der Konfigurationsdatei fest.

Ergebnis

JSDoc ist ein leistungsstarkes Tool zur Dokumentation von JavaScript-Code, das Entwicklern nicht nur hilft, ihren Code besser zu verstehen, sondern auch die automatische Generierung von API-Dokumentation ermöglicht.