it-swarm.com.de

Tools und Anleitung zur Dokumentation von TypeScript-Code?

Gibt es Tools zum Generieren von Dokumentation für TypeScript-Quellcode? Oder sollte ich etwas generisches wie NaturalDocs verwenden? Welcher Stil wird für die Blockkommentare empfohlen/welche sind für ein eigenständiges Dokumentationsvolumen vorgesehen?.

Sollte ich es benutzen:

///<foo>bar</foo> MSVS kind of comments?

oder

/** @javadoc style comments */

oder vielleicht

/*
  Something like this?
 */

Ich habe Angst, /// Zu verwenden, weil es für Importe verwendet wird, und ich möchte nicht auf eine andere zukünftige Funktion eingehen, die möglicherweise auf ähnliche Weise eingeführt wurde - aber Sie wissen es nie ...

Oder ist es möglich, dokumentiertes JavaScript aus TypeScript zu generieren und dann die JavaScript-Toolchain zu verwenden?

55
user797257

Vielleicht etwas spät, aber nachdem ich auf dieses Problem gestoßen war, stellte ich fest, dass es immer noch keine Werkzeuge gab, um dies zu tun. Also gabelte ich den TS-Compiler und erstellte den Code dafür.

Forked TypeScript-Compiler-Projekt in Version 0.9.0.1 hat dann eine Option "--documentation" hinzugefügt, mit der aus jedem JSDoc, das Sie in den Code einfügen, eine Wiki-Dokumentation erstellt wird (keine für die reine Ausgabe von Methoden/Eigenschaften usw. erforderlich).

https://TypeScript.codeplex.com/SourceControl/network/forks/EdwardNutting/TypeScriptDocumentationGeneration

Es werden .ts.wiki-Dateien erstellt (deren Inhalt zum direkten Hochladen auf CodePlex usw. geeignet ist, wenn Sie auch die neuen Parameter --wikiRemoveRoot und --wikiSourceRoot verwenden - siehe fork - meine erste Commit-Beschreibung). Oder Sie könnten den Code anpassen, um HTML zu erzeugen (was relativ einfach wäre - ich habe die harte Arbeit des Mangelns des Compilers/DelcrationEmitter erledigt :))

Hoffe das hilft (entweder dir oder zukünftigen Lesern dieser Frage)

Ed

22
Ed Nutting

Ich habe gerade ein Tool namens TypeDoc veröffentlicht, das HTML-API-Dokumentationsseiten aus TypeScript * .ts-Dateien generiert.

Der Dokumentationsgenerator führt den TypeScript-Compiler aus und extrahiert die Typinformationen aus den generierten Compilersymbolen. Daher müssen Sie keine zusätzlichen Metadaten in Ihre Kommentare aufnehmen.

Wenn Sie es ausprobieren möchten, installieren Sie das Tool einfach und führen Sie es über npm aus:

npm install typedoc --global
typedoc --out path/to/documentation/ path/to/TypeScript/project/

Wenn Sie wissen möchten, wie eine mit TypeDoc erstellte Dokumentation aussieht, gehen Sie zur GitHub-Seite des Projekts:

http://typedoc.org/ | https://github.com/TypeStrong/typedoc

91
sebastian-lenz

Sie können diese Art von Kommentaren über Ihrer Funktion verwenden.

/** 
* Comment goes here
*/

Und als nächstes, wenn Sie Ihre Methode treffen, wird es mit Dokumentation angezeigt.

12
Daniil T.

XML-Dokumentkommentare generieren eines der vorgeschlagenen Probleme für die TypeScript-Sprache.

Derzeit unterstützen TypeScript-Tools JSDoc Ankündigung von TypeScript 0.8.2 .

Sie möchten also definitiv den JSDoc-Stil für Kommentare verwenden. Wenn Sie Kommentare nur für IntelliSense benötigen, wird die Verwendung von JSDoc Ihre Anforderungen abdecken. Wenn Sie Kommentare benötigen, weil Sie Ihren API-Verbrauchern Dokumentation bereitstellen möchten, sollten Sie Deklarationsdateien (* .d.ts) mit Kommentaren verwenden. Wenn Sie eine Nice-Dokumentation im Web erstellen möchten - ich denke, es wird einfach zu warten sein, wenn das TypeScript-Team die Generierung von XML-Dokumentkommentaren implementiert (oder diese von Hand schreibt).

6
outcoldman

Ich kompiliere mit JavaScript und benutze jsduck ( https://github.com/senchalabs/jsduck ), um eine API-Dokumentation basierend auf den JavaScript-Dateien zu generieren. Solange Sie tsc nicht anweisen, Kommentare zu entfernen, die einwandfrei funktionieren, mit Ausnahme von Feldern ohne Standardwert (!).

module example {

/**
 * My class description
 * @class example.MyClass
 */
export class MyClass {
    /**
     * Description of my property
     * @property {String} myProperty
     */
    myProperty: string = null;

    /**
     * This property will be removed in compiled JavaScript, that's why
     * this documentation will not be visible in jsduck.
     */
    willNotWork: string;

    /**
     * Description of my method
     * @method myFunction
     * @param {String} myParam
     */
    myFunction(myParam: string): void {
    }
}

} // end of module
3

Ich habe ein Tool zum Generieren von HTML-Dokumentation aus Deklarationsdateien (.d.ts) geschrieben hier . Es bietet grundlegende Unterstützung für Kommentare im JSDoc-Stil.

Kompilieren Sie Ihre TypeScript-Quelldateien mit dem -d -c Optionen zum Generieren von Deklarationsdateien und zum Beibehalten von Kommentaren. Nach der Installation können Sie dann ausführen

TypeScript-docs *.d.ts

hTML-Dokumentation auf Standardausgabe zu generieren.

Verwenden Sie, um die Ausgabe in einer Datei zu speichern

TypeScript-docs *.d.ts --output=path/to/output.html

0
Phil Freeman