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

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

本节书摘来自异步社区《编写可维护的JavaScript》一书中的第2章,第2.4节,作者:【美】Nicholas C. Zakas著,更多章节内容可以访问云栖社区“异步社区”公众号查看

2.4 文档注释

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

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

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

传入一个单独的对象,会创建一个它的浅拷贝(shallow copy)。

如果需要深拷贝(deep copy),请使用'clone()'
@method merge
@param {Object} 被合并的一个或多个对象
@return {Object} 一个新的合并后的对象
**/
Y.merge = function () {
     var args    = arguments,
          i       = 0,
          len     = args.length,
          result  = {};
     for (; i < len; ++i) {
          Y.mix(result, args[i], true);
     }
     return result;
};

YUI类库使用它自己的一个名叫YUIDoc的工具来根据这些注释生成文档。但是,它的格式几乎和JSDoc Toolkit(类库无关的)一模一样,在开源项目中JSDoc Toolkit的应用非常广泛,包括Google内部的很多开源项目。YUIDoc和JSDoc Toolkit之间的重要区别是,YUIDoc同时支持文档注释中的HTML和Markdown格式,而JSDoc Toolkit只支持HTML。

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

所有的方法

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

所有的构造函数

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

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

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

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

相关文章
|
14天前
|
JavaScript 前端开发 容器
 JavaScript 遍历文档生成目录结构
 JavaScript 遍历文档生成目录结构
14 1
|
27天前
|
JavaScript 前端开发 Java
小笔记:如何使用代码注释:关于JavaScript与TypeScript 注释和文档的自动生成
小笔记:如何使用代码注释:关于JavaScript与TypeScript 注释和文档的自动生成
89 0
|
27天前
|
JSON JavaScript 前端开发
Danfo.js专题 - 附:Dnotebook(Danfo Notebook)单机资源与汉化文档
Danfo.js专题 - 附:Dnotebook(Danfo Notebook)单机资源与汉化文档
31 0
|
4月前
|
XML JavaScript 前端开发
SAP UI5 本地开发如何实现 XML 和 JavaScript 代码的自动完成和嵌入式 API 文档自动显示试读版
SAP UI5 本地开发如何实现 XML 和 JavaScript 代码的自动完成和嵌入式 API 文档自动显示试读版
54 0
|
2月前
|
存储 JavaScript 前端开发
JavaScript DOM 操作:什么是文档碎片(Document Fragment)?有什么作用?
JavaScript DOM 操作:什么是文档碎片(Document Fragment)?有什么作用?
42 0
|
7月前
|
XML JavaScript 前端开发
|
6月前
|
JavaScript 前端开发
JavaScript — DOM的增删改查、节点、事件、文档的加载
JavaScript — DOM的增删改查、节点、事件、文档的加载
76 0
|
7月前
|
Web App开发 JavaScript 安全
利用pdf.js在线展示PDF文档
利用pdf.js在线展示PDF文档
180 0
|
7月前
|
JavaScript 前端开发 BI
百度地图POI多信息点标注开发说明文档(php+layui+mysql+百度javascript API2.0+echarts4.8)
百度地图POI多信息点标注开发说明文档(php+layui+mysql+百度javascript API2.0+echarts4.8)
86 0
|
7月前
|
前端开发 JavaScript IDE
JavaScript的文档生成器
大多数 IDE 包含主语言的文档生成器。因为 JavaScript 没有官方 IDE,所以过去文档要么手动生成, 要么借用其他语言的文档生成器生成。不过,目前已出现了一些面向 JavaScript 的文档生成器。
168 0

相关产品

  • 云迁移中心