web-dev-qa-db-fra.com

Outils et guide pour documenter le code TypeScript?

Existe-t-il des outils pour générer de la documentation pour le code source TypeScript? Ou devrais-je utiliser quelque chose de générique comme NaturalDocs? Quel serait le style recommandé pour les commentaires de bloc/ceux destinés au volume de documentation autonome.

Dois-je utiliser:

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

ou

/** @javadoc style comments */

ou peut-être

/*
  Something like this?
 */

J'ai peur d'utiliser /// car il est utilisé pour les importations, et je ne veux pas marcher sur une autre fonctionnalité future éventuellement introduite de la même manière - mais on ne sait jamais ...

Ou est-il possible de générer du JavaScript documenté à partir de TypeScript, puis d'utiliser la chaîne d'outils JavaScript?

typescriptdocumentation-generation
55
user797257

Peut-être un peu tard mais après avoir rencontré ce problème, j'ai trouvé qu'il n'y avait toujours pas d'outils pour le faire. J'ai donc bifurqué le compilateur TS et créé le code pour le faire.

Le projet de compilateur TypeScript bifurqué à v0.9.0.1 a ensuite ajouté une option "--documentation" qui générera la documentation wiki à partir de tout JSDoc que vous mettrez dans le code (aucun requis pour une sortie simple des méthodes/propriétés, etc.)

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

Il produit des fichiers .ts.wiki (dont le contenu peut être téléchargé directement sur CodePlex, etc. si vous utilisez également les nouveaux paramètres --wikiRemoveRoot et --wikiSourceRoot - voir fork - ma première description de validation). Ou vous pouvez adapter le code pour produire du HTML (ce qui serait relativement simple - j'ai fait le travail acharné de manipuler le compilateur/delcrationEmitter :))

J'espère que cela vous aidera (vous ou les futurs lecteurs de cette question)

Ed

22
Ed Nutting

Je viens de publier un outil appelé TypeDoc qui génère des pages de documentation api html à partir de fichiers TypeScript * .ts.

Le générateur de documentation exécute le compilateur TypeScript et extrait les informations de type à partir des symboles de compilateur générés. Par conséquent, vous n'avez pas à inclure de métadonnées supplémentaires dans vos commentaires.

Si vous voulez l'essayer, installez et exécutez simplement l'outil via npm:

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

Si vous voulez savoir à quoi ressemble une documentation créée avec TypeDoc, rendez-vous sur la page GitHub du projet:

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

91
sebastian-lenz

Vous pouvez utiliser ce type de commentaire au-dessus de votre fonction.

/** 
* Comment goes here
*/

Et ensuite, lorsque vous atteindrez votre méthode, elle apparaîtra avec la documentation.

12
Daniil T.

Générer des commentaires XML Doc l'un des problèmes proposés pour le langage TypeScript.

Pour l'instant, les outils TypeScript prennent en charge JSDoc Annonce TypeScript 0.8.2 .

Donc, vous voulez certainement utiliser le style JSDoc pour les commentaires. Si vous avez besoin de commentaires uniquement pour IntelliSense - l'utilisation de JSDoc couvrira votre besoin. Si vous avez besoin de commentaires parce que vous souhaitez fournir de la documentation à vos clients API - vous devez utiliser des fichiers de déclaration (* .d.ts) avec des commentaires. Si vous voulez générer de la documentation Nice sur le web - je suppose qu'il sera facile d'attendre quand l'équipe TypeScript implémentera la génération de commentaires de doc XML (ou l'écrira à la main).

6
outcoldman

Je compile en JavaScript et j'utilise jsduck ( https://github.com/senchalabs/jsduck ) pour générer une documentation api basée sur les fichiers JavaScript. Tant que vous ne dites pas à tsc de supprimer les commentaires qui fonctionnent parfaitement, à l'exception des champs sans valeur par défaut (!).

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
Christoph Lütjen

J'ai écrit un outil pour générer de la documentation HTML à partir de fichiers de déclaration (.d.ts) ici . Il a un support de base pour les commentaires de style JSDoc.

Compilez vos fichiers source TypeScript avec le -d -c options pour générer des fichiers de déclaration et conserver les commentaires. Ensuite, après l'installation, vous pouvez exécuter

TypeScript-docs *.d.ts

pour générer de la documentation HTML sur la sortie standard.

Pour enregistrer la sortie dans un fichier, utilisez

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

0
Phil Freeman