web-dev-qa-db-ja.com

TypeScriptコードを文書化するためのツールとガイド？

TypeScriptソースコードのドキュメントを生成するツールはありますか？または、NaturalDocsのような一般的なものを使用する必要がありますか？ブロックコメント/スタンドアロンボリュームのドキュメント向けのコメントの推奨スタイルは何ですか？.

使用する必要があります：

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

または

/** @javadoc style comments */

多分

/*
  Something like this?
 */

///はインポートに使用されるので使用するのが怖いです。また、同様の方法で導入される可能性のある他の将来の機能を踏みにじりたくはありません。

または、TypeScriptから文書化されたJavaScriptを生成し、JavaScriptツールチェーンを使用することは可能ですか？

typescriptdocumentation-generation
55
user797257

少し遅かったかもしれませんが、この問題に遭遇した後、これを行うためのツールがまだないことがわかりました。そこで、TSコンパイラを分岐し、それを実行するコードを作成しました。

V0.9.0.1のフォークされたTypeScriptコンパイラプロジェクトは、コードに入力したJSDocからwikiドキュメントを生成する「--documentation」オプションを追加しました（メソッド/プロパティなどの単なる出力には必要ありません）。

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

.ts.wikiファイルを生成します（新しい--wikiRemoveRootおよび--wikiSourceRootパラメーターも使用する場合、その内容はCodePlexなどに直接アップロードするのに適しています-fork-私の最初のコミットの説明を参照）。または、HTMLを生成するようにコードを適合させることもできます（これは比較的単純です-コンパイラ/ delcrationEmitterをマングリングするという大変な作業を行いました:)）

これがお役に立てば幸いです（あなたまたはこの質問の将来の読者）

エド

22
Ed Nutting

TypeScript * .tsファイルからhtml APIドキュメントページを生成するTypeDocというツールをリリースしました。

ドキュメントジェネレーターは、TypeScriptコンパイラーを実行し、生成されたコンパイラーシンボルから型情報を抽出します。したがって、コメントに追加のメタデータを含める必要はありません。

試してみたい場合は、npmでツールをインストールして実行してください。

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

TypeDocで作成されたドキュメントがどのようなものかを知りたい場合は、プロジェクトのGitHubページに移動してください。

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

91
sebastian-lenz

関数の上でこの種のコメントを使用できます。

/** 
* Comment goes here
*/

そして、次にメソッドをヒットすると、ドキュメントが表示されます。

12
Daniil T.

XMLドキュメントコメントの生成 TypeScript言語で提案されている問題の1つ。

今のところ、TypeScriptツールはJSDocをサポートしています TypeScript 0.8.2の発表 。

したがって、コメントには必ずJSDocスタイルを使用する必要があります。 IntelliSenseについてのみコメントが必要な場合-JSDocを使用すると要件が満たされます。 APIコンシューマーにドキュメントを提供するためにコメントが必要な場合は、コメント付きの宣言ファイル（* .d.ts）を使用する必要があります。 WebでNiceドキュメントを生成する場合-TypeScriptチームがXMLドキュメントコメントの生成を実装する（または手で記述する）のを待つのは簡単だと思います。

6
outcoldman

JavaScriptにコンパイルし、jsduck（ https://github.com/senchalabs/jsduck ）を使用して、JavaScriptファイルに基づいてAPIドキュメントを生成します。デフォルト値（！）のないフィールドを除いて、完全に機能するコメントを削除するようにtscに指示しない限り。

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

宣言（.d.ts）ファイルからHTMLドキュメントを生成するツールを作成しました here 。 JSDocスタイルのコメントを基本的にサポートしています。

-d -cオプションを使用してTypeScriptソースファイルをコンパイルし、宣言ファイルを生成してコメントを保持します。その後、インストール後に実行できます

TypeScript-docs *.d.ts

標準出力でHTMLドキュメントを生成します。

出力をファイルに保存するには、次を使用します

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

0
Phil Freeman