摘要
JSDoc 规范是 JavaScript 最为流行的一套 JS 注释规范，许多 IDE 编辑器都对其提供内核或插件级别的支持。 根据 JSDoc 规范书写注释的 JavaScript 文件，可以借助 JSDoc 工具生成标准的使用文档，也可以被 IDE 编辑器用于代码提示。 JSDoc 默认的文档模板比较单调，docstrap 提供了 14+ 种 bootstrap 风格的模板，使用 docstrap 使得生成的文档更美观易用。 下面志文工作室针对 JSDoc 与 docstrap 安装使用的方法与要点作简要介绍。
JSDoc 规范是 JavaScript 最为流行的一套 JS 注释规范，许多 IDE 编辑器都对其提供内核或插件级别的支持。
根据 JSDoc 规范书写注释的 JavaScript 文件，可以借助 JSDoc 工具生成标准的使用文档，也可以被 IDE 编辑器用于代码提示。
JSDoc 默认的文档模板比较单调，docstrap 提供了 14+ 种 bootstrap 风格的模板，使用 docstrap 使得生成的文档更美观易用。
下面志文工作室针对 JSDoc 与 docstrap 安装使用的方法与要点作简要介绍。
一、安装 JSDoc 与 Docstrap
首先进入项目根目录。
1.1 安装 JSDoc
npm i -g jsdoc
1.2 安装 Docstrap
npm i ink-docstrap
移除 Docstrap 对 google 字体的引用
由于引用了 google 字体，国内环境下会导致页面卡顿。
打开 node_modules\ink-docstrap\template\static\styles 目录，将所有引用 google 字体的内容删除：
@import url("https://fonts.googleapis.com/css?family=Roboto:400,500");
Docstrap 模板配置项说明参考：
"templates": {
"systemName" : "{string}",
"footer" : "{string}",
"copyright" : "{string}",
"includeDate" : "{boolean}",
"navType" : "{vertical|inline}",
"theme" : "{theme}",
"linenums" : "{boolean}",
"collapseSymbols" : "{boolean}",
"inverseNav" : "{boolean}",
"outputSourceFiles" : "{boolean}" ,
"outputSourcePath" : "{boolean}",
"dateFormat" : "{string}",
"syntaxTheme" : "{string}",
"sort" : "{boolean|string}"
}
Docstrap 提供了一个默认的配置文件可供参考：
node_modules\ink-docstrap\template\jsdoc.conf.json
二、创建和编辑 JSDoc 配置文件
JSDoc 提供的默认配置文件在这里：
node_modules\jsdoc\gen.json
结合 JSDoc 和 Docstrap 的默认配置，我们创建一个项目使用的配置文件。
在项目目录新建一个 json 文件，如：jsdoc-conf.json，内容参考如下：
{
"tags": {
"allowUnknownTags": true
},
"source": {
"include": ["src"], //JavaScript 文件(目录)列表
"exclude": ["src/core", "src/ui"], //在 include 中需要过滤的文件(目录)
"includePattern": ".+\\.(js|es)$" //正则过滤符合规则的文件
},
"plugins": ["plugins/markdown"], //使用markdown 插件
"markdown": {
tags: ["file"], //增加额外需要解析的标签
"excludeTags": ["author"], //排除不用解析的标签
"parser": "gfm", //gfm
"hardwrap": true //允许多行
},
"templates": { //模板配置，包含了 DocStrap 的配置参数
//"logoFile": "images/logo.png", //logo 文件路径
"cleverLinks": false,
"monospaceLinks": false,
"dateFormat": "ddd MMM Do YYYY", //当需要打印日期时使用的格式
"outputSourceFiles": true, //是否输出文件源码
"outputSourcePath": true, //是否输出源码路径
"systemName": "Common Modules", //系统名称
"footer": "", //页脚内容
"copyright": "https://lzw.me.", //页脚版权信息
"navType": "vertical", //vertical 或 inline
//docstrap 模板主题。可取值: cosmo, cyborg, flatly, journal, lumen, paper,
//readable, sandstone, simplex, slate, spacelab, superhero, united, yeti
"theme": "cosmo",
"linenums": true, //是否显示行号
"collapseSymbols": false, //是否折叠太长的内容
"inverseNav": true, //导航是否使用 bootstrap 的 inverse header
"protocol": "html://", //生成文档使用的阅读协议
"methodHeadingReturns": true //method 方法标题上是否包含返回类型
},
//命令行执行参数配置。在这里配置了后
//命令行只需要执行: jsdoc -c jsdoc-conf.json 即可
"opts": {
//"template": "templates/default", //使用 JSDoc 默认模板
"template": "./node_modules/ink-docstrap/template", //使用 docstrap 模板
"destination": "./docs/", //输出目录。等同于 -d ./out/
"recurse": true, //是否递归查找。 -r
"debug": true, //启用调试模式。--debug
"readme": "README.md" //要写到文档首页的 readme 文档。-R README.md
}
}
参考如上的示例说明编写你自己的配置。确认无误，在项目目录下执行如下命令，即可生成项目 API 文档：
jsdoc -c ./jsdoc-conf.json
注意点：
- 只使用配置文件中的 opts 配置命令行参数。即只使用 -c 参数指定配置文件。因为命令行的参数与配置文件中可能出现重叠，那么就会存在优先级、合并等问题。在不清楚这些问题的情况下，可能会出现各种细节的问题。
- source 部分的配置，应简洁清晰明了。这里的 include/exclude/includePattern/excludePattern 以及命令行中附带的文件路径，存在着优先级以及合并的问题。
- 推荐配置 markdown 插件，这对详细注释很有帮助。
- 遇到错误或奇怪的问题时，多查阅官方文档。JSDoc 中文文档
- 理解名称路径，有利于书写和生成更合适的文档。
- ES6 模块化方式，某些情况下对导出模块的声明，可借助 @alisas 标签。示例
/**
* @file test
* @module test
*/
let abc = 'abc...';
/**
* @alias module:test
*/
const test = {
abc: abc
};
export default test;
三、使用 IDE 编辑器插件
通过 IDE 插件，在编辑器中可以快速的插入 JSDoc 规范的注释。大型的 IDE 则甚至在内核中已集成相关功能。
sublime text 插件
DocBlockr (https://github.com/spadgos/sublime-jsdocs)
vscode 插件
add jsdoc comments
四、相关参考
官方使用文档： http://usejsdoc.org/
JSDoc 中文文档： http://www.css88.com/doc/jsdoc/
HBuilder JSDoc+规范: http://ask.dcloud.net.cn/article/129
JSDuck: https://github.com/senchalabs/jsduck
