Question

是否有任何工具可以为TypeScript源代码生成文档？或者我应该使用像NaturalDocs这样的通用名称？块注释的推荐样式/用于独立文档量的那些样式。

我应该使用：

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

或

/** @javadoc style comments */

或者

/*
  Something like this?
 */

我害怕使用///，因为它用于导入，我不想继续以类似方式引入的其他未来功能 - 但你永远不知道...

或者是否可以从TypeScript生成文档化的JavaScript，然后使用JavaScript工具链？

Answer 1

我刚刚发布了一个名为TypeDoc的工具，可以使用TypeScript * .ts文件生成html api文档页面。

文档生成器运行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

Answer 2

也许有点晚了但在我遇到这个问题之后我发现仍然没有工具可以做到这一点。所以我分叉了TS编译器并创建了代码来实现它。

在v0.9.0.1上的Forked TypeScript编译器项目然后添加了一个“--documentation”选项，它将从您放入代码中的任何JSDoc生成wiki文档（只需要方法/属性的简单输出等）< / p>

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

它生成.ts.wiki文件（如果你也使用新的--wikiRemoveRoot和--wikiSourceRoot参数，那么它的内容适合直接上传到CodePlex等等 - 参见fork - 我的第一个提交描述）。或者您可以调整代码来生成HTML（这将相对简单 - 我已经完成了编译/ delcrationEmitter的艰苦工作:)）

希望这会有所帮助（无论是您还是此问题的未来读者）

版

Answer 3

您可以在功能上方使用此类评论。

/** 
* Comment goes here
*/

接下来当你点击你的方法时，它会显示文档。

Answer 4

Generate XML Doc comments针对TypeScript语言提出的一个问题。

目前，TypeScript工具支持JSDoc Announcing TypeScript 0.8.2。

因此，您肯定希望使用JSDoc样式进行评论。如果您只需要IntelliSense的注释 - 使用JSDoc将满足您的要求。如果您需要提供注释，因为您想为API使用者提供文档 - 您应该使用带注释的声明文件（* .d.ts）。如果你想在网上生成很好的文档 - 我想当TypeScript团队实现XML文档注释的生成（或者手工编写）时，很容易等待。

Answer 5

我正在编译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

Answer 6

我编写了一个工具，用于从声明（.d.ts）文件here生成HTML文档。它对JSDoc风格的注释有基本的支持。

使用-d -c选项编译TypeScript源文件，以生成声明文件并保留注释。然后在安装后，您可以运行

typescript-docs *.d.ts

在标准输出上生成HTML文档。

要将输出保存到文件，请使用

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

用于记录TypeScript代码的工具和指南？

6 个答案: