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

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文档(只需要方法/属性的简单输出等)

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

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

希望这会有所帮助(无论是你或未来读者的这个问题)

埃德

Answer 3

您可以在函数上方使用此类注释.

/** 
* Comment goes here
*/

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

Answer 4

生成XML Doc注释是TypeScript语言的建议问题之一.

目前,TypeScript工具支持JSDoc 宣布TypeScript 0.8.2.

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