Eine ordnungsgemäße Codedokumentation ist für die Wartbarkeit von entscheidender Bedeutung. Mit JSDocs können Sie es direkt in Ihren Code einbetten, sodass es immer zur Hand ist.

Die ordnungsgemäße Codedokumentation ist ein wichtiger, aber oft übersehener Aspekt der Softwareentwicklung. Als Entwickler sind Sie es gewohnt, sauberen, effizienten Code zu schreiben, haben aber möglicherweise weniger Erfahrung im Schreiben guter Dokumentation.

Eine gute Dokumentation ist für alle nützlich, die mit Ihrem Code arbeiten, unabhängig davon, ob es sich um andere Mitglieder Ihres Teams oder um Sie selbst zu einem späteren Zeitpunkt handelt. Es kann erklären, warum Sie etwas auf eine bestimmte Weise implementiert haben oder wie Sie eine bestimmte Funktion oder API verwenden.

Für JavaScript-Entwickler ist JSDoc eine gute Möglichkeit, mit der Dokumentation Ihres Codes zu beginnen.

Was ist JSDoc?

Das Dokumentieren von Code kann komplex und mühsam sein. Allerdings erkennen immer mehr Menschen die Vorteile von

instagram viewer
ein „Dokumente als Code“-Ansatz, und viele Sprachen verfügen über Bibliotheken, die dabei helfen, den Prozess zu automatisieren. Für eine einfache, klare und prägnante Dokumentation. Genau wie die Go-Sprache hat GoDoc Um die Dokumentation aus dem Code zu automatisieren, verfügt JavaScript über JSDoc.

JSDoc generiert Dokumentation, indem es spezielle Kommentare in Ihrem JavaScript-Quellcode interpretiert, diese Kommentare verarbeitet und maßgeschneiderte Dokumentation erstellt. Anschließend stellt es diese Dokumentation in einem barrierefreien HTML-Format zur Verfügung.

Dadurch bleibt die Dokumentation im Code, sodass Sie die Dokumentation problemlos aktualisieren können, wenn Sie Ihren Code aktualisieren.

JSDoc einrichten

Die Entwickler von JSDoc haben den Einstieg und die Einrichtung von JSDoc in Ihrem JavaScript-Projekt vereinfacht.

Um JSDoc lokal zu installieren, führen Sie Folgendes aus:

npm install --save-dev jsdoc

Dadurch wird die Bibliothek als Entwicklungsabhängigkeit in Ihrem Projekt installiert.

Um JSDoc zu verwenden, verwenden Sie spezielle Syntaxkommentare in Ihrem Quellcode. Sie werden alle Ihre Dokumentationskommentare darin verfassen /** Und */ Markierungen. Darin können Sie definierte Variablen, Funktionen, Funktionsparameter und vieles mehr beschreiben.

Zum Beispiel:

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

Der @param Und @kehrt zurück Tags sind zwei der vielen speziellen Schlüsselwörter, die JSDoc zur Erläuterung Ihres Codes unterstützt.

Um die Dokumentation für diesen Code zu generieren, führen Sie Folgendes aus: npx jsdoc gefolgt vom Pfad zu Ihrer JavaScript-Datei.

Zum Beispiel:

npx jsdoc src/main.js

Wenn Sie JSDoc global installiert haben, können Sie das weglassen npx Flagge und Lauf:

jsdoc path/to/file.js

Dieser Befehl generiert eine aus Ordner in Ihrem Projektstammverzeichnis. Im Ordner finden Sie HTML-Dateien, die die Seiten Ihrer Dokumentation darstellen.

Sie können die Dokumentation einsehen unter Einrichten eines lokalen Webservers zum Hosten, oder einfach durch Öffnen der Datei out/index.html in einem Browser. Hier ist ein Beispiel dafür, wie eine Dokumentationsseite standardmäßig aussehen wird:

Konfigurieren der JSDoc-Ausgabe

Sie können eine Konfigurationsdatei erstellen, um das Standardverhalten von JSDoc zu ändern.

Erstellen Sie dazu eine conf.js Datei und exportieren Sie ein JavaScript-Modul in diese Datei.

Zum Beispiel:

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

In der Konfigurationsdatei sind verschiedene JSDoc-Konfiguration Optionen. Der Vorlage Mit dieser Option können Sie eine Vorlage verwenden, um das Erscheinungsbild der Dokumentation anzupassen. Die Community von JSDoc bietet viele Vorlagen das du nutzen kannst. Mit dem Paket können Sie auch Ihre eigenen personalisierten Vorlagen erstellen.

Um den Speicherort der generierten Dokumentation zu ändern, legen Sie fest Ziel config-Option in ein Verzeichnis einfügen. Das obige Beispiel gibt a an Dokumente Ordner im Stammverzeichnis des Projekts.

Verwenden Sie diesen Befehl, um JSDoc mit einer Konfigurationsdatei auszuführen:

jsdoc -c /path/to/conf.js

Um die Ausführung dieses Befehls zu vereinfachen, fügen Sie ihn als hinzu Skripte Eintrag in Ihrem package.json Datei:

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

Du kannst jetzt Führen Sie den npm-Skriptbefehl aus innerhalb eines Terminals.

Ein Beispiel für eine mit JSDoc generierte Dokumentation

Unten finden Sie eine einfache Arithmetikbibliothek mit hinzufügen Und subtrahieren Methoden.

Dies ist ein Beispiel für gut dokumentierten JavaScript-Code:

/**
 * 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 ...
};

Die JSDoc-Kommentare bieten eine klare und umfassende Beschreibung der Bibliothek und ihrer Methoden, einschließlich:

  • Eine Beschreibung der Bibliothek und ihres Zwecks.
  • Die Parameter jeder Methode, einschließlich ihres Typs und einer kurzen Beschreibung.
  • Der Wert und Typ, den jede Methode zurückgibt.
  • Die Fehler, die jede Methode auslösen kann, und die Bedingungen, die sie verursachen.
  • Ein Beispiel für die Verwendung der einzelnen Methoden.

Die Kommentare umfassen auch die @Modul Tag, um anzugeben, dass es sich bei dieser Datei um ein Modul handelt und das @Beispiel Tag, um ein Codebeispiel für jede Methode bereitzustellen.

Entwicklercode richtig dokumentieren

Wie Sie sehen, ist JSDoc ein sehr nützliches Tool, um Ihnen den Einstieg in die Dokumentation von JavaScript-Code zu erleichtern. Dank der einfachen Integration können Sie beim Schreiben Ihres Codes schnell eine detaillierte Dokumentation erstellen. Sie können die Dokumentation auch direkt in Ihrem Arbeitsbereich pflegen und aktualisieren.

So nützlich die Automatisierung von JSDoc auch ist, Sie sollten sich dennoch an bestimmte Richtlinien halten, damit Sie qualitativ hochwertige Dokumentation erstellen können.