60

是否有任何工具可以为 TypeScript 源代码生成文档？或者我应该使用像 NaturalDocs 这样通用的东西吗？块注释的推荐样式/用于独立文档卷的样式是什么。

我应该使用：

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

或者

/** @javadoc style comments */

也许

/*
  Something like this?
 */

我害怕使用///，因为它用于进口，而且我不想涉足可能以类似方式引入的其他一些未来功能 - 但你永远不知道......

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

4

6 回答 6

94

我刚刚发布了一个名为 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

于 2014-06-02T20:15:56.420 回答
23

这个答案来自 2013 年。现在存在其他（维护的）解决方案 - 其中一些在下面的答案中提到。

原答案：

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

v0.9.0.1 的分叉 TypeScript 编译器项目然后添加了一个“--documentation”选项，该选项将从您放入代码中的任何 JSDoc 生成 wiki 文档（对于方法/属性等的普通输出不需要）

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

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

希望这会有所帮助（您或此问题的未来读者）

埃德

于 2013-08-15T22:18:34.177 回答
13

您可以在函数上方使用这种注释。

/** 
* Comment goes here
*/

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

于 2014-09-09T17:52:48.447 回答
7

生成 XML 文档评论TypeScript 语言的建议问题之一。

目前 TypeScript 工具支持 JSDoc宣布 TypeScript 0.8.2。

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

于 2013-04-28T16:57:22.240 回答
4

我正在编译为 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
于 2014-06-27T15:51:31.147 回答
0

我在这里编写了一个用于从声明 (.d.ts) 文件生成 HTML 文档的工具。它对 JSDoc 样式的注释有基本的支持。

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

typescript-docs *.d.ts

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

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

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

于 2013-09-26T05:14:40.963 回答