JSDoc

JSDOC ist ein Auszeichnungssprache verwendet, um zu kommentieren JavaScript Quellcode Dateien. Verwendung Kommentare Programmierer, die JSDOC enthält, können Dokumentation hinzufügen, die die beschreiben, die die beschreiben Programmierschnittstelle des Code, den sie erstellen. Dies wird dann durch verschiedene Tools verarbeitet, um Dokumentation in zugänglichen Formaten wie zu erstellen Html und Rich-text-Format. Die JSDOC -Spezifikation wird unter veröffentlicht CC BY-SA 3.0, während sein Begleiter Dokumentationsgenerator und Parser Library ist gratis Software unter dem Apache -Lizenz 2.0.

Geschichte

JSDOCs Syntax und Semantik ähneln denen der der Javadoc Schema, das zum Dokumentieren von Code in Java verwendet wird. JSDOC unterscheidet sich von Javadoc, da es spezialisiert ist, JavaScripts zu verarbeiten dynamisch Verhalten.^[1]

Ein frühes Beispiel, das eine Javadoc-ähnliche Syntax zum Dokumentieren von JavaScript verwendet hat, wurde 1999 mit dem veröffentlicht Netscape/Mozilla Projekt Nashorn, ein JavaScript Laufzeitsystem geschrieben in Java. Es enthielt ein Spielzeug "JSDOC" -HTML -Generator mit bis zu 1,3, als Beispiel für seine JavaScript -Funktionen.^[2]

Alle Hauptgenerationen von "JSDOC" wurden von Micmaths (Michael Mathews) geleitet. Er begann 2001 mit JSDOC.pm, einem einfachen System in Perlin Zusammenarbeit mit dem kanadischen Programmierer Gabriel Reid. Es wurde veranstaltet SourceForge in einem CVS -Repository.^[3] Von JSDOC 1.0 (2007) hat er das System in JavaScript (erneut für Rhino) neu geschrieben und nach einer Reihe von Erweiterungen JSDOC 2.0 (2008) den Namen "Jsdoc-Toolkit" erhielt. Unter dem MIT -Lizenz, es wurde in einem veranstaltet Subversion -Repository an Google -Code.^[4] Bis 2011 hat er das System in JSDOC 3.0 umgestaltet und das Ergebnis auf veranstaltet GitHub. Es läuft jetzt weiter Node.js.^[1]

JSDOC -Tags

Einige der beliebtesten Annotations -Tags, die in der modernen JSDOC verwendet werden, sind:

Schild	Beschreibung
@Autor	Name des Entwicklers
@Konstrukteur	Markiert eine Funktion als Konstruktor
@veraltet	Markiert eine veraltete Methode
@Ausnahme	Synonym für @throws
@exports	Identifiziert ein Mitglied, das vom Modul exportiert wird
@param	Dokumentiert einen Methodeparameter; Ein Datentyp -Indikator kann zwischen lockigen Zahnspangen hinzugefügt werden
@Privatgelände	Bedeutet, dass ein Mitglied privat ist
@kehrt zurück	Dokumentiert einen Rückgabewert
@Rückkehr	Synonym für @kehrt zurück
@sehen	Dokumentiert eine Vereinigung zu einem anderen Objekt
@machen	Dokumentiert etwas, das fehlt/geöffnet ist
@Dies	Gibt den Typ des Objekts an, dem das Schlüsselwort Dies bezieht sich innerhalb einer Funktion.
@throws	Dokumentiert eine Ausnahme, die mit einer Methode ausgelöst wird
@Ausführung	Bietet die Versionsnummer einer Bibliothek

Beispiel

/** @class Circle, der einen Kreis darstellt. */ Klasse Kreis { /**  * Erstellt eine Instanz des Kreises.  *  * @Author: Moi  * @param {number} r der gewünschte Radius des Kreises.  */  Konstrukteur(r) {  /** @Privatgelände */ Dies.Radius = r  /** @Privatgelände */ Dies.Umfang = 2 * Mathematik.PI * r  }  /**    * Erstellt einen neuen Kreis aus einem Durchmesser.    *    * @param {number} D Der gewünschte Durchmesser des Kreises.    * @return {circle} Das neue Kreisobjekt.    */  statisch Fromdiameter(d) {  Rückkehr Neu Kreis(d / 2)  }  /**    * Berechnet den Umfang des Kreises.    *    * @deprecated seit 1.1.0; Verwenden Sie stattdessen GetCircirferference    * @return {number} Der Umfang des Kreises.    */  CalculateCircircumference() {  Rückkehr 2 * Mathematik.PI * Dies.Radius  }  /**    * Gibt den vorbereiteten Umfang des Kreises zurück.    *    * @return {number} Der Umfang des Kreises.    * @Since 1.1.0    */  GetCircirate() {  Rückkehr Dies.Umfang  }  /**    * Finden Sie eine String -Darstellung des Kreises.    *    * @Override    * @return {String} menschlich-lesbare Darstellung dieses Kreises.    */  tostring() {  Rückkehr `[Ein Kreisobjekt mit Radius von $ {Dies.Radius}.] `  } } /**  * Druckt einen Kreis.  *  * @param {circle} circle  */ Funktion printcircle(Kreis) {    /** @this {circle}*/    Funktion gebunden() { Konsole.Protokoll(Dies) }  gebunden.anwenden(Kreis) } 

Notiere dass der @class und @constructor TAGs können in der Tat weggelassen werden: Die ECMasyntax reicht aus, um ihre Identität klar zu machen, und JSDOC nutzt dies.^[5] @override kann auch automatisch abgeleitet werden.^[6]

JSDOC verwendet

• Googles Schließungsinter und Verschluss Compiler. Letztere extrahiert die Typinformationen, um das Ausgabe -JavaScript zu optimieren.
• Typoskript Kann die Typ -Prüfung für JavaScript -Dateien mit Anmerkungen vom Typ JSDOC durchführen.^[7] Microsoft hat eine neue TSDOC -Sprache mit erweiterbaren Tags angegeben.
• Beliebter Redakteur Erhabener Text Unterstützt JSDOC über das Docblockr- oder Doxydoxygen -Plugin
• Die JSDOC -Syntax wurde im Apressbuch ausführlich beschrieben Grundlagen von Ajax ISBN1-59059-582-3.
• Intellij Idee, NetBeans, Visual Studio -Code und Rubry JSDOC -Syntax verstehen.
• Eclipse-basiert Aptana Studio Unterstützt scriptDoc.
• MozileDer Mozilla -Inline -Editor verwendet jsdoc.pm.
• Das Helma Anwendungsrahmen verwendet JSDOC.
• Die Sproutcore -Dokumentation wurde mit JSDOC generiert. [1]
• Visual Studio, Webstorm und viele weitere Integrierte Entwicklungsumgebungen oder Textredakteure Angebot Code -Abschluss und andere Unterstützung auf der Grundlage von JSDOC -Kommentaren.
• Open Source Atom Der Herausgeber unterstützt JSDOC über die Atom-Easy-Jsdoc Plugin.

Siehe auch

• Vergleich der Dokumentationsgeneratoren
• Google Closeure Tools

Verweise

Externe Links

• Offizielle JSDOC -Website, für Tutorials und Dokumente zur Verwendung
• Offizieller JSDOC Githubfür aktuellen Code
• "JavaScript für den Verschluss Compiler" Annotieren ", Dokumentation der Schließtools, Google Developer -Website