JSDoc入门使用指南 -- 手摸手教你用JSDoc（超好用的js文档生成工具）

安装

准备

• Node.js 8.15.0+

通过npm安装

• 全局安装：npm install -g jsdoc

  • 若出现权限问题，如 EACCES报错，最佳实践为用node版本管理器（nvm等）重装npm
• 本地安装：npm install --save-dev jsdoc
  • 命令行工具目录：./node_modules/.bin/jsdoc

鉴于JSDoc的文档生成工具的本质，建议使用 --save-dev的本地安装模式

 

使用

书写JSDoc标签

jsdoc的使用方式非常简单，在编写代码时根据jsdoc的规则在块级注释中添加相应标签即可：

/**
* 功能：将时间戳格式化为指定格式的字符串
* @param {Number} milliSec - 要转换的时间，可以为秒、毫秒、微秒、或Date类型
* @param {String} [formatStr] - 目标格式字符串 可选 默认为：'yyyy-MM-dd hh:mm:ss'
* @returns {String} - 根据目标时间格式，将时间数值（或Date）转换成的时间字符串
*/
function formatTime(milliSec, formatStr = DEFAULT_FORMAT_STR) {
    // code
}

其中 @param、@returns即为jsdoc的常用标签，具体标签及用法可通过传送门到官网或中文文档查看

 

生成JSDoc文档

代码编写完成后，即可通过命令行生成jsdoc文档

基本用法

• /path/to/jsdoc yourSourceCodeFile.js

// 全局安装
jsdoc yourSourceCodeFile.js
// 本地安装
./n