js文件生成html说明文档,使用 JSDoc 与 docstrap 生成 JavaScript 项目 API 文档

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 插件

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