用于记录 TypeScript 代码的工具和指南？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/16263480/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Tools and guide for documenting TypeScript code?
提问by sebastian-lenz
Are there any tools for generating documentation for TypeScript source code? Or should I use something generic like NaturalDocs? What would be the recommended style of the block comments / those intended for standalone volume of documentation.
是否有任何工具可以为 TypeScript 源代码生成文档？或者我应该使用像 NaturalDocs 这样的通用工具吗？什么是块注释的推荐风格/那些用于独立文档卷的风格。
Should I use:
我应该使用：
///<foo>bar</foo> MSVS kind of comments?
or
或者
/** @javadoc style comments */
or perhaps
也许
/*
Something like this?
*/
I'm afraid to use ///because it is used for imports, and I don't want to tread on some other future feature possibly introduced in the similar way - but you never know...
我害怕使用，///因为它用于导入，而且我不想使用可能以类似方式引入的其他未来功能 - 但你永远不知道......
Or is it possible to generate documented JavaScript from TypeScript and then use the JavaScript toolchain?
或者是否可以从 TypeScript 生成文档化的 JavaScript，然后使用 JavaScript 工具链？
采纳答案by Ed Nutting
This answer is from 2013. Other (maintained) solutions exist now - some of which are mentioned in answers below.
这个答案来自 2013 年。现在存在其他（维护的）解决方案 - 其中一些在下面的答案中提到。
Original answer:
原答案：
Maybe a bit late but after I came across this problem I found there were still no tools to do this. So I forked the TS compiler and created the code to do it.
也许有点晚了，但在我遇到这个问题后，我发现仍然没有工具可以做到这一点。所以我分叉了 TS 编译器并创建了代码来完成它。
Forked TypeScript compiler project at v0.9.0.1 then added a "--documentation" option that will generate wiki documentation from whatever JSDoc you put in the code (none required for just plain output of methods/properties etc. )
在 v0.9.0.1 分叉 TypeScript 编译器项目然后添加了一个“--documentation”选项，该选项将从您放入代码的任何 JSDoc 生成 wiki 文档（仅方法/属性等的纯输出不需要）
It produces .ts.wiki files (contents of which is suitable for uploading straight to CodePlex etc. if you also use the new --wikiRemoveRoot and --wikiSourceRoot params as well - see fork - my first commit description). Or you could adapt the code to produce HTML (which would be relatively simple - I've done the hard work of mangling the compiler/delcrationEmitter :) )
它生成 .ts.wiki 文件（如果您还使用新的 --wikiRemoveRoot 和 --wikiSourceRoot 参数，则其内容适合直接上传到 CodePlex 等 - 请参阅 fork - 我的第一个提交描述）。或者您可以调整代码以生成 HTML（这相对简单 - 我已经完成了修改编译器/delcrationEmitter :) 的艰巨工作）
Hope this helps (either you or future readers of this question)
希望这会有所帮助（您或此问题的未来读者）
Ed
埃德
回答by sebastian-lenz
I have just released a tool called TypeDoc that generates html api documentation pages out of TypeScript *.ts files.
我刚刚发布了一个名为 TypeDoc 的工具，它可以从 TypeScript *.ts 文件中生成 html api 文档页面。
The documentation generator runs the TypeScript compiler and extracts the type information from the generated compiler symbols. Therefore you don't have to include any additional metadata within your comments.
文档生成器运行 TypeScript 编译器并从生成的编译器符号中提取类型信息。因此，您不必在评论中包含任何其他元数据。
If you want to try it out, simply install and run the tool through npm:
如果您想尝试一下，只需通过 npm 安装并运行该工具：
npm install typedoc --global
typedoc --out path/to/documentation/ path/to/typescript/project/
If you want to know what a documentation created with TypeDoc looks like, head over to the GitHub page of the project:
如果您想知道使用 TypeDoc 创建的文档是什么样的，请访问该项目的 GitHub 页面：
回答by Daniil T.
You can use this kind of commenting above your function.
您可以在函数上方使用这种注释。
/**
* Comment goes here
*/
And next when you will hit your method it will show up with documentation.
接下来，当您点击您的方法时，它将显示文档。
回答by outcoldman
Generate XML Doc commentsone of the proposed issues for TypeScript language.
生成 XML 文档注释是 TypeScript 语言的建议问题之一。
For now TypeScript tools support JSDoc Announcing TypeScript 0.8.2.
目前 TypeScript 工具支持 JSDoc宣布 TypeScript 0.8.2。
So, you definitely want to use JSDoc style for comments. If you need comments only for IntelliSense - using JSDoc will cover your requirement. If you need comments because you want to provide documentation for your API consumers - you should use declaration files (*.d.ts) with comments. If you want to generate nice documentation on web - I guess it will be easy to just wait when TypeScript team will implement generation of XML doc comments (or write it by hand).
因此，您肯定希望使用 JSDoc 样式进行注释。如果您只需要 IntelliSense 的评论 - 使用 JSDoc 将满足您的要求。如果您因为想为 API 使用者提供文档而需要注释 - 您应该使用带有注释的声明文件 (*.d.ts)。如果你想在 Web 上生成好的文档 - 我想等待 TypeScript 团队实现 XML 文档注释的生成（或手工编写）会很容易。
回答by Christoph Lütjen
I'm compiling to JavaScript and use jsduck (https://github.com/senchalabs/jsduck) to generate api documentation based on the JavaScript files. As long as you don't tell tsc to remove comments that works perfectly, except of fields without a default value(!).
我正在编译为 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
回答by Phil Freeman
I've written a tool for generating HTML documentation from declaration (.d.ts) files here. It has basic support for JSDoc-style comments.
我已经编写了一个工具，用于从声明 (.d.ts) 文件中生成 HTML 文档here。它对 JSDoc 风格的注释有基本的支持。
Compile your TypeScript source files with the -d -coptions to generate declaration files and preserve comments. Then after installation, you can run
使用-d -c生成声明文件和保留注释的选项编译您的 TypeScript 源文件。然后安装后，你可以运行
typescript-docs *.d.ts
typescript-docs *.d.ts
to generate HTML documentation on standard output.
在标准输出上生成 HTML 文档。
To save output to a file, use
要将输出保存到文件，请使用
typescript-docs *.d.ts --output=path/to/output.html
typescript-docs *.d.ts --output=path/to/output.html
