Die Leistungsfähigkeit von jsDoc | Komentor

Viele Entwickler beschweren sich (aus guten Gründen) über die schwache Typisierung von Javascript. Aus diesem Grund haben wir den Aufstieg von Typescript erlebt.
Aber so ordentlich es auch ist, Typescript hat einige Einschränkungen.

  • Hartes Tippen
  • Ihr Code wird analysiert und geändert
  • Zusätzlicher Schritt zum Bauen
  • Neue Syntax zum Lernen

Meistens sind diese leicht zu behandeln oder einfach zu ignorieren. Wo jsDoc Wirklich gut ist, dass es die Schmerzen schwacher Art ohne Nachteile lindert und sogar auf den Tisch legt.

Was es ist

Sehen wir uns zunächst ein komplexes Beispiel an, das wir in diesem Tutorial rekonstruieren werden.


class Pony extends Animal {
    
    constructor (name, color = Pony.colors.white) {
        super(name);
        this.color = color;
        
        this.age = 0;
    }

    
    run (...through) {
        console.log("Run through ", ...through);
        return this;
    }

    
    
    static get colors () {
        return {
            white: "#fff",
            black: "#333",
            foxy: "#c57432",
        };
    }
}

Und hier ist eine Demo der Vorteile (unter Verwendung von Webstorm). Sehen Sie sich die QuickInfos zur automatischen Vervollständigung genau an.

animiertes Demo-GIF

Gehen wir es nun Schritt für Schritt durch.

Beschreibung

Die einfachste Verwendung von jsDoc ist die Beschreibung einer Funktion oder einer Klasse.


class Pony extends Animal {
    
    constructor (name, color = Pony.colors.white) {
        
    }

    
    run (...through) {
        
    }

    
    static get colors () {
        
    }
}

Jetzt hat jeder, der den von Ihnen geschriebenen Code verwendet, einige Informationen über den Zweck jeder Funktion oder Klasse.
Abhängig von Ihrer IDE oder Ihrem Editor wird es in einem Tooltip angezeigt, wenn die automatische Vervollständigung gestartet wird.

Parameter

In der Einleitung habe ich über die Variablentypen in JS gesprochen. Hier gehen wir das Problem an.
Mit JsDoc können Sie angeben, welche Parameter mit welchem ​​Typ (oder Typen) von einer Funktion erwartet werden. Dann sollte Ihre Entwicklungsumgebung Sie warnen, wenn Sie einen Parameter mit inkompatiblem Typ angeben.


constructor (name, color = Pony.colors.white) {
    
}

Gleichzeitig können Sie die Verwendung der Variablen schnell beschreiben.
Wenn ein Parameter optional ist, schließen Sie ihn einfach in Klammern ein und geben Sie gegebenenfalls den Standardwert an.


constructor (name, color = Pony.colors.white) {
    
}

Wir können die Auswirkung noch einmal auf die Autovervollständigung sehen.

params Typ Demo

Typ/Callback-Definition

Manchmal müssen Sie möglicherweise benutzerdefinierte Typen definieren, um einige Daten zu beschreiben, die Sie nicht in eine Klasse einschließen möchten.


Auf diese Weise können Sie jedem Element eines Objekts einen Typ und eine Beschreibung zuweisen.

Typ-Definition-Demo

Dasselbe gilt für einen erwarteten Parameter, beachten Sie Folgendes:



function ponyFactory (data) {
    
}

Das CustomData Typ wird in einem @typedef-Block erklärt. Die Typdefinition kann andere mit dem @extends-Tag erweitern. Das ist wirklich cool 8)

Wenn eine Funktion einen Callback erwartet (z. B. ein typisches Array-Traverse), können Sie anzeigen, welche Parameter an diesen Callback übergeben werden.



function herd (callback) {
    
}

Weiter und darüber hinaus

Die jsDoc-Dokumentation hat eine viele Tags für Sie zu verwenden. Jeder ermöglicht es Ihnen, den Benutzer besser über Ihren Code zu informieren.

Lobende Erwähnung an @return (definieren Sie den zurückgegebenen Typ), @abstract (diese Klasse sollte nicht instanziiert werden), @type (geben Sie einen Typ für eine beliebige Variable an), @example (zeigen Sie ein Anwendungsbeispiel) …

Denken Sie daran, dass Sie die meiste Zeit derjenige sind, der Ihren eigenen Code pflegt. Sie tun sich also wirklich einen Dienst, indem Sie den von Ihnen geschriebenen Code dokumentieren.

Und nicht zuletzt gibt es sie zahlreiche Möglichkeiten um die gesamte Dokumentation zu analysieren und vollständig formatierte Markdowns auszugeben, um beispielsweise Ihre API zu dokumentieren.

Similar Posts

Leave a Reply

Your email address will not be published.