是否有为TypeScript源代码生成文档的工具?或者我应该使用一些通用的东西,比如NaturalDocs?块注释的推荐样式是什么?/那些用于独立文档卷的注释。
我应该使用:
///<foo>bar</foo> MSVS kind of comments?
或
/** @javadoc style comments */
或者
/*
Something like this?
*/
我害怕使用///
,因为它是用于导入的,而且我不想践踏其他可能以类似方式引入的其他功能-但是你永远不会知道…
还是可以从TypeScript生成文档化的JavaScript,然后使用JavaScript工具链?
我刚刚发布了一个叫做TypeDoc的工具,它可以从TypeScript *中生成html api文档页面。ts文件。
文档生成器运行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
这个答案来自2013年。现在存在其他(维护的)解决方案-其中一些在下面的答案中提到。
原始答:
可能有点晚了,但当我遇到这个问题时,我发现仍然没有工具可以做到这一点。所以我分叉了TS编译器并创建了相应的代码。
v0.9.0.1版本的TypeScript编译器项目,然后添加了一个"——documentation"选项,它将从你在代码中放入的任何JSDoc生成wiki文档(对于方法/属性等的普通输出不需要)
https://typescript.codeplex.com/SourceControl/network/forks/EdwardNutting/TypeScriptDocumentationGeneration生成.ts。wiki文件(内容适合直接上传到CodePlex等,如果你也使用新的——wikiRemoveRoot和——wikiSourceRoot参数,以及-见fork -我的第一次提交描述)。或者您可以调整代码以生成HTML(这将相对简单-我已经完成了混淆编译器/delcrationEmitter:)的艰苦工作)
希望这对你或将来的读者有所帮助
爱德你可以在你的函数上面使用这种注释。
/**
* Comment goes here
*/
然后当你点击你的方法时它会显示文档。
生成XML文档注释了TypeScript语言的一个建议问题。
现在TypeScript工具支持JSDoc宣布TypeScript 0.8.2.
所以,你肯定想使用JSDoc风格的注释。如果您只需要为智能感知提供注释,那么使用JSDoc将满足您的需求。如果你需要注释,因为你想为你的API消费者提供文档——你应该使用带有注释的声明文件(*.d.ts)。如果你想在web上生成漂亮的文档,我想只要等待TypeScript团队实现XML文档注释的生成(或者手工编写)就可以了。
我正在编译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
我编写了一个工具,用于从声明(.d.ts)文件生成HTML文档。它支持jsdoc风格的注释。
用-d -c
选项编译TypeScript源文件,生成声明文件并保留注释。安装完成后,可以运行
typescript-docs *.d.ts
在标准输出上生成HTML文档。
将输出保存到文件中,使用
typescript-docs *.d.ts --output=path/to/output.html