r23maps.js - Dokumentation

Kommentare helfen, den Programmcode besser zu verstehen. Und noch besser geht es, wenn wir spezielle Kommentar-Tags und den „JSDoc 3“ einsetzen. Der folgende Beitrag zeigt, wie es geht.

Je umfangreicher ein Projekt wird, desto wichtiger wird die Dokumentation. Eine Klassen- oder Funktions-Bibliothek wächst mit der Zeit so stark an, dass selbst der Programmierer nicht mehr durchblickt, welche Funktion wofür vorgesehen ist und welche Parameter sie verlangt. Um sich stundenlanges Suchen im Code und das erneute Studieren der Klasse zu ersparen, sollte man den Code von Anfang an dokumentieren.

In Anlehnung an das „Javadoc Tool“ gibt es mit „JSDoc 3“ für JavaScript eine Dokumentationsmöglichkeit mit Code-Kommentaren und Annotationen. Die geschriebenen Kommentare werden durch moderne IDEs wie etwa NetBeans 8 eingelesen und helfen der IDE dabei, Vorschläge beim Schreiben von Code (Auto-Completion) zu machen oder Dokumentationen anzuzeigen.

Erstellen von JSDoc-Kommentaren für JavaScript r23maps.js

r23maps.js in Visual Studio zeigt Informationen an, die Sie einem Skript mit standardmäßigen JSDoc-Kommentaren hinzufügen. Sie können JSDoc-Kommentare verwenden, um Informationen zu Codeelementen wie z. B. Funktionen, Felder und Variablen bereitzustellen.
JSDoc-Kommentartags

Die folgenden standardmäßigen JSDoc-Kommentartags werden von IntelliSense verwendet, um Informationen zu Ihrem Code anzuzeigen.

JSDoc-Tag Syntax Notizen
@deprecated @deprecated Beschreibung Gibt eine veraltete Funktion oder Methode an.
@description @description Beschreibung Gibt die Beschreibung für eine Funktion oder Methode an.
@param @param {Typ} ParameternameBeschreibung Gibt Informationen für einen Parameter in einer Funktion oder Methode an.

TypeScript unterstützt auch @paramTag.

@property @property {Typ} Eigenschaftsname Gibt Informationen an, darunter eine Beschreibung, die entweder für ein Feld oder für einen Member gilt, der über ein Objekt definiert wird.
@returns @returns {Typ} Gibt einen Rückgabewert an.

Verwenden Sie für TypeScript @returnType statt @returns.

@summary @summary Beschreibung Gibt die Beschreibung für eine Funktion oder Methode an (identisch mit @description).
@type @type {Typ} Gibt den Typ für eine Konstante oder eine Variable an.
@typedef @typedef {Typ} benutzerdefinierterTypname Gibt einen benutzerdefinierten Typ an.