使用 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

注意点：

只使用配置文件中的 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

正文完

发表至：前端开发

2016-06-28

0

转载说明：除特殊说明外本站文章皆由CC-4.0协议发布，转载请注明出处。

在 Angular-cli 中引入 simple-mock 实现前端开发 API Mock 接口数据模拟

nodeJS 中从命令行等待并读入用户输入实现与用户交互的方法

修改系统设置让 Chrome 浏览器支持音频自动播放

CSS3 Flex 弹性盒模型与文本内容居中

终端中的彩色文本：ANSI 字符颜色控制指令的格式构成简介

MacBook 下连接小米路由器 Smb 功能共享与复制文件的方法

CSS BEM 命名规范简介

使用 mocha 和 chai 进行基于浏览器的 javascript 异步测试

pt 与 px、em、rem 的区别与换算

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

摘要

一、安装 JSDoc 与 Docstrap

1.1 安装 JSDoc

1.2 安装 Docstrap

二、创建和编辑 JSDoc 配置文件

三、使用 IDE 编辑器插件

sublime text 插件

vscode 插件

四、相关参考

npm 仓库私有包离线化安装方案

Python 环境管理工具 Miniconda 的安装、配置与使用

IOS：Xcode 15 IOS 17 Simulator 模拟器下载失败的解决办法

iOS 开发无证书签名IPA安装真机测试，一种支持iOS应用多开的方法

macOS 使用 launchctl 和 crontab 设置定时任务的方法

免费电影网站的另一种打开方式：批量下载、边看边播不卡顿、支持 Docker 部署、永久免费！

使用 RSS 订阅：个人高效阅读知识补充指南

高性能 Python 包管理器 uv 的安装与使用

Dify 工作流执行自定义代码报错：`Run failed: error: operation not permitted`

Python 环境管理工具 Miniconda 的安装、配置与使用

	"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}"
	}

	{
	"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
	}
	}

	/**
	* @file test
	* @module test
	*/

	let abc = 'abc...';

	/**
	* @alias module:test
	*/
	const test = {
	abc: abc
	};

	export default test;