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

2016-06-28 0 条评论 7,212 次阅读被赞了 12 次

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