使用 JSDoc 与 docstrap 生成 JavaScript 项目 API 文档

9,528次阅读
没有评论

共计 3275 个字符,预计需要花费 9 分钟才能阅读完成。

摘要

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

注意点:

  1. 只使用配置文件中的 opts 配置命令行参数。即只使用 -c 参数指定配置文件。因为命令行的参数与配置文件中可能出现重叠,那么就会存在优先级、合并等问题。在不清楚这些问题的情况下,可能会出现各种细节的问题。
  2. source 部分的配置,应简洁清晰明了。这里的 include/exclude/includePattern/excludePattern 以及命令行中附带的文件路径,存在着优先级以及合并的问题。
  3. 推荐配置 markdown 插件,这对详细注释很有帮助。
  4. 遇到错误或奇怪的问题时,多查阅官方文档。JSDoc 中文文档
  5. 理解名称路径,有利于书写和生成更合适的文档。
  6. 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

正文完
 0
任侠
版权声明:本站原创文章,由 任侠 于2016-06-28发表,共计3275字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
验证码