《编写可维护的JavaScript》——2.4 文档注释

本节书摘来自异步社区《编写可维护的javascript》一书中的第2章，第2.4节，作者：【美】nicholas c. zakas著，更多章节内容可以访问云栖社区“异步社区”公众号查看

从技术的角度讲，文档注释并不是javascript的组成部分，但它们是一种普遍的实践。文档注释有很多种格式，但最流行的一种格式来自于javadoc文档格式：多行注释以单斜线加双星号（/**）开始，接下来是描述信息，其中使用@符号来表示一个或多个属性。来看一段来自yui的源码的例子。

<code>/**</code>

返回一个对象，这个对象包含被提供对象的所有属性。

后一个对象的属性会覆盖前一个对象的属性。

传入一个单独的对象，会创建一个它的浅拷贝（shallow copy）。

yui类库使用它自己的一个名叫yuidoc的工具来根据这些注释生成文档。但是，它的格式几乎和jsdoc toolkit（类库无关的）一模一样，在开源项目中jsdoc toolkit的应用非常广泛，包括google内部的很多开源项目。yuidoc和jsdoc toolkit之间的重要区别是，yuidoc同时支持文档注释中的html和markdown格式，而jsdoc toolkit只支持html。

这里强烈推荐你使用文档生成工具来为你的javascript生成文档。javascript代码注释必须符合你所用的工具支持的格式，但很多文档生成工具都支持javadoc风格的文档注释。当使用文档注释时，你应当确保对如下内容添加注释。

所有的方法

应当对方法、期望的参数和可能的返回值添加注释描述。

所有的构造函数

应当对自定义类型和期望的参数添加注释描述。

所有包含文档化方法的对象

如果一个对象包含一个或多个附带文档注释的方法，那么这个对象也应当适当地针对文档生成工具添加文档注释。

当然，注释的详细格式和用法最终还是由你所选择的文档生成工具决定的。