blocks|key|110902|text|Generate+XML+Doc+comments是TypeScript语言提出的问题之一。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|110903|目前，TypeScript工具支持JSDoc+Announcing+TypeScript+0.8.2。|110904|因此，您肯定希望对注释使用JSDoc样式。如果你只需要IntelliSense的注释--使用JSDoc就可以满足你的需求。如果您需要注释，因为您想为您的API使用者提供文档-您应该使用带有注释的声明文件(*.d.ts)。如果你想在网络上生成更好的文档，我想等待TypeScript团队实现XML文档注释的生成(或者手动编写)是很容易的。|110905|entityMap|0|LINK|mutability|MUTABLE|url|https://typescript.codeplex.com/workitem/16|1|http://blogs.msdn.com/b/typescript/archive/2013/01/21/announcing-typescript-0-8-2.aspx^0|0|P|0|0|N|R|1|0|0^^$0|@$1|2|3|4|5|6|7|R|8|@]|9|@$A|S|B|T|1|U]]|C|$]]|$1|D|3|E|5|6|7|V|8|@]|9|@$A|W|B|X|1|Y]]|C|$]]|$1|F|3|G|5|6|7|Z|8|@]|9|@]|C|$]]|$1|H|3|-4|5|6|7|10|8|@]|9|@]|C|$]]]|I|$J|$5|K|L|M|C|$N|O]]|P|$5|K|L|M|C|$N|Q]]]]

<a href="https://typescript.codeplex.com/workitem/16">Generate XML Doc comments</a> one of the proposed issues for TypeScript language. 

For now TypeScript tools support JSDoc <a href="http://blogs.msdn.com/b/typescript/archive/2013/01/21/announcing-typescript-0-8-2.aspx">Announcing TypeScript 0.8.2</a>.

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).

blocks|key|328391|text|我已经编写了一个从声明(.d.ts)文件here生成HTML文档的工具。它对JSDoc风格的注释有基本的支持。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|328392|使用-d+-c选项编译您的TypeScript源文件，以生成声明文件并保留注释。然后，在安装之后，您可以运行|style|CODE|328393|typescript-docs+*.d.ts|328394|生成关于标准输出的HTML文档。|328395|要将输出保存到文件，请使用|328396|typescript-docs+*.d.ts+--output=path/to/output.html|328397|entityMap|0|LINK|mutability|MUTABLE|url|https://github.com/paf31/typescript-docs^0|K|4|0|0|2|5|0|0|M|0|0|0|0|1F|0^^$0|@$1|2|3|4|5|6|7|X|8|@]|9|@$A|Y|B|Z|1|10]]|C|$]]|$1|D|3|E|5|6|7|11|8|@$A|12|B|13|F|G]]|9|@]|C|$]]|$1|H|3|I|5|6|7|14|8|@$A|15|B|16|F|G]]|9|@]|C|$]]|$1|J|3|K|5|6|7|17|8|@]|9|@]|C|$]]|$1|L|3|M|5|6|7|18|8|@]|9|@]|C|$]]|$1|N|3|O|5|6|7|19|8|@$A|1A|B|1B|F|G]]|9|@]|C|$]]|$1|P|3|-4|5|6|7|1C|8|@]|9|@]|C|$]]]|Q|$R|$5|S|T|U|C|$V|W]]]]

I've written a tool for generating HTML documentation from declaration (.d.ts) files <a href="https://github.com/paf31/typescript-docs" rel="nofollow">here</a>. It has basic support for JSDoc-style comments.

Compile your TypeScript source files with the <code>-d -c</code> options to generate declaration files and preserve comments. Then after installation, you can run

<code>
typescript-docs *.d.ts
</code>

to generate HTML documentation on standard output.

To save output to a file, use

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

blocks|key|328424|text|我刚刚发布了一个名为TypeDoc的工具，它可以从TypeScript+*.ts文件生成html+api文档页面。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|328425|文档生成器运行TypeScript编译器，并从生成的编译器符号中提取类型信息。因此，您不必在注释中包含任何其他元数据。|328426|如果您想尝试一下，只需通过npm安装并运行该工具：|328427|npm+install+typedoc+--global
typedoc+--out+path/to/documentation/+path/to/typescript/project/|code-block|syntax|javascript|328428|如果您想了解使用TypeDoc创建的文档是什么样子，请转到项目的GitHub页面：|328429|http://typedoc.org/+%7C+https://github.com/TypeStrong/typedoc|offset|length|328430|entityMap|0|LINK|mutability|MUTABLE|url|http://typedoc.org/|1|https://github.com/TypeStrong/typedoc^0|0|0|0|0|0|0|J|0|M|11|1|0^^$0|@$1|2|3|4|5|6|7|10|8|@]|9|@]|A|$]]|$1|B|3|C|5|6|7|11|8|@]|9|@]|A|$]]|$1|D|3|E|5|6|7|12|8|@]|9|@]|A|$]]|$1|F|3|G|5|H|7|13|8|@]|9|@]|A|$I|J]]|$1|K|3|L|5|6|7|14|8|@]|9|@]|A|$]]|$1|M|3|N|5|6|7|15|8|@]|9|@$O|16|P|17|1|18]|$O|19|P|1A|1|1B]]|A|$]]|$1|Q|3|-4|5|6|7|1C|8|@]|9|@]|A|$]]]|R|$S|$5|T|U|V|A|$W|X]]|Y|$5|T|U|V|A|$W|Z]]]]

I have just released a tool called TypeDoc that generates html api documentation pages out of TypeScript *.ts files.

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.

If you want to try it out, simply install and run the tool through npm:

<pre><code>npm install typedoc --global
typedoc --out path/to/documentation/ path/to/typescript/project/
</code></pre>

If you want to know what a documentation created with TypeDoc looks like, head over to the GitHub page of the project:

<a href="http://typedoc.org/">http://typedoc.org/</a> | <a href="https://github.com/TypeStrong/typedoc">https://github.com/TypeStrong/typedoc</a>

blocks|key|111026|text|我正在编译成JavaScript，并使用jsduck+(https://github.com/senchalabs/jsduck)根据JavaScript文件生成api文档。只要你不告诉tsc删除正常工作的注释，除了没有默认值(！)的字段。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|111027|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|code-block|syntax|javascript|111028|entityMap|0|LINK|mutability|MUTABLE|url|https://github.com/senchalabs/jsduck^0|S|10|0|0|0^^$0|@$1|2|3|4|5|6|7|Q|8|@]|9|@$A|R|B|S|1|T]]|C|$]]|$1|D|3|E|5|F|7|U|8|@]|9|@]|C|$G|H]]|$1|I|3|-4|5|6|7|V|8|@]|9|@]|C|$]]]|J|$K|$5|L|M|N|C|$O|P]]]]

I'm compiling to JavaScript and use jsduck (<a href="https://github.com/senchalabs/jsduck" rel="nofollow">https://github.com/senchalabs/jsduck</a>) 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(!).

<pre><code>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
</code></pre>

blocks|key|111063|text|你可以在你的函数上使用这种注释。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|111064|/**+
*+Comment+goes+here
*/|code-block|syntax|javascript|111065|下一步，当你点击你的方法时，它将与文档一起出现。|111066|entityMap^0|0|0|0^^$0|@$1|2|3|4|5|6|7|K|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|L|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|M|8|@]|9|@]|A|$]]|$1|I|3|-4|5|6|7|N|8|@]|9|@]|A|$]]]|J|$]]

You can use this kind of commenting above your function.

<pre><code>/** 
* Comment goes here
*/
</code></pre>

And next when you will hit your method it will show up with documentation.

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.

Should I use:

<pre><code>///&lt;foo&gt;bar&lt;/foo&gt; MSVS kind of comments?
</code></pre>

or

<pre><code>/** @javadoc style comments */
</code></pre>

or perhaps

<pre><code>/*
 Something like this?
 */
</code></pre>

I'm afraid to use <code>///</code> 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?

Tools and guide for documenting TypeScript code?

翻译质量差，导致语言生硬或混乱。

没有提供实际的解决方法或示例。

解答不清晰，无法理解或解决问题。

页面排版不美观，阅读体验差。

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

有没有为TypeScript源代码生成文档的工具？或者我应该使用像NaturalDocs这样的泛型？块注释/用于独立文档卷的注释的推荐样式是什么？我应该使用：///<foo>bar</foo> MSVS kind of comments?或/** @javadoc style comments */或者也许/* So...

问记录TypeScript代码的工具和指南？
EN

Stack Overflow用户

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问记录TypeScript代码的工具和指南？EN