jsDoc注释规范

jsDoc，顾名思义，jsDoc是一个用于JavaScript的API文档生成器，类似于Javadoc或phpDocumentor。它根据JavaScript文件中的注释信息，生成JS应用程序或模块的API文档。通过使用JSDoc标记如：命名空间，类，方法参数等，从而使开发者能够轻易地阅读代码，掌握代码定义的类和和其属性和方法，从而降低维护成本并提高开发效率。
JSDoc中文文档
JSDoc官网
JSDoc注释通常应该放在代码被记录之前。为了被JSDoc解析器识别，每个注释必须以/**序列开头,以便由JSDoc解析器识别。

/**
** 这是一段简单的JsDoc注释。
*/

一、常用注释规范

1.1 @constructor 构造函数声明注释

@constructor明确一个函数 是某个类的构造函数

1.2 @param 参数注释

通过@param来表示函数、类的方法的参数。@param是最常用的注释标签。参数标签可表示 一个参数的参数名、参数类型和参数描述的注释。通过参数注释，可以在vscode中联想出相应的参数类型，让开发更便捷。如：

/**
* 表示一本书
* @constructor
* @param {string} title - 书名
* @param {string} author - 作者
*
*/
function Book(title,author){}

let book = new Book('aaa','bbb')

• param {string} title ： 表示给参数title增加一个string类型。这个类型可以是string,number,boolean这类基础数据类型，也可以是复杂数据类型如object

/**
 * 
 * @param {Object} book 
 * @param {string} book.title
 * @param {string} book.author
 */

function buyBook(book) {    }

// 数组参数
/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
Project.prototype.assign = function(employees) {
    // ...
}; 

// 可选参数
/**
 * @param {string} [somebody] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
} 

• param {object} book : 这样我们在使用book的使用就会提示出所有的属性和方法！

1.3 @return 返回值注释

表示一个函数 的返回值，如果函数没有显示指定返回值可以不写。用法与@param类似，区别在于return只有一个，所以不用指定参数名。

/**
* @return {Number} 返回值描述
*/
function test () { }

// 函数返回 Promise 实例的情况可以这么指定类型
/**
 * @return {Promise<number>}
 */
function testPromise () {
  return new Promise((res) => {
    res(1)
  })
}

1.4 @example 示例注释

用于表示示例代码，通常示例的代码会另起一行编写

/**
* @author Mondo 
* @description list 数据结构 转换成 树结构
* @param {Array} data 需要转换的数据
* @param {String} id 节点 id
* @param {String} pid 父级节点 id
* @param {String} child 子树为节点对象的某个属性值
* @param {Object} labels 需要新增的字段名集合 { label: 'category_name' }
* @return {Array}
*
* @example
* formatListToTree({data: [{id:1}, {id: 2}, {id: 3, pid: 1}]})
* =>
* [ { id: 1, children: [ {id: 3, pid: 1} ] }, { id: 2 } ]
*/

function formatListToTree({
  data = [],
  id = "id",
  pid = "pid",
  child = "children",
  labels = null
}) {
...
}

• @author 该类/方法的作者。
• @class 表示这是一个类。
• @function/@method 表示这是一个函数/方法(这是同义词)。
• @private 表示该类/方法是私有的，JSDOC 不会为其生成文档。
• @name 该类/方法的名字。
• @description 该类/方法的描述。
• @param 该类/方法的参数，可重复定义。
• @return 该类/方法的返回类型。
• @link 创建超链接，生成文档时可以为其链接到其他部分。
• @example 创建例子。

1.5 @typedef和@property 自定义类型

使用@typedef和@property 定义一个类型，然后在其他地方使用

/**
* @typedef {Object} Book
* @property {string} title 书名
* @property {string} author 	作者
*/

/**
* @param {Book} bo 要收藏的书对象
*/
function collectBook(bo){}

1.6 文件注释

/**
 * @file  jsdoc测试文件
 * @author wujing
 * @copyright no
 * @createDate 2022-05-07 16:22
 */

1.7 变量注释

/**
 * @var {object}
 * @desc 变量定义
 * @property {string} a 属性a
 * @property {string} b 属性b
 */

 var foo = {
     a: 'a',
     b: 'b'
}

1.8 常量注释

/**
 * 
 * @constant {string}
 * @default #000
 * @desc 颜色定义
 */
const COLOR_WHITE = '#FFF';

1.9 方法注释

/**
 * @methor 
 * @param {Type} data={} 目标对象
 * @example 
 * {
 *      target: 手机号
 * }
 * @return {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 *
 */
function matchNumber(data){
    return '返回对象'
}

1.10 回调函数

/**
 * This callback type is called `requestCallback` and is displayed as a global symbol.
 *
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
/**
 * Does something asynchronously and executes the callback on completion.
 * @param {requestCallback} cb - The callback that handles the response.
 */
function doSomethingAsynchronously(cb) {
    // code
}; 

二、通过JSDoc生成文档网站

类似于我们平常对接口用到的swagger一样，借助JSDoc也可生成类似网站

2.1 安装

# 全局安装
npm install jsdoc -g
# 或者 局部安装
npm install jsdoc -save-dev

2.2 使用

1、基本使用

运动命令后，默认生成out文件夹，包含编译后的文档（html）部署后即可通过文档来看各文件方法说明

jsdoc a.js b.js ...

2、配置使用

在项目下定义 jsdoc.json 配置文件，通过 -c 参数来指定

# 方式一：生成配置文件
jsdoc -c jsdoc.json

# 方式二： 在package.json中的scripts添加命令。 这样通过npm run docs即可生成文档
{
	"scripts": {
  	"docs": "jsdoc -c jsdoc.json"
  }
}

3、配置文件

{
  "source": {
    "include": [ "src/" ],	
    "exclude": [ "src/libs" ]
  },
  "opts": {
    "template": "templates/default",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true,
    "verbose": false
  }
}

• source 表示传递给 JSDOC 的文件
• source.include 表示 JSDOC 需要扫描哪些文件
• source.exclude 表示 JSDOC 需要排除哪些文件
• opts 表示传递给 JSDOC 的选项
• opts.template 生成文档的模板，默认是 templates/default
• opts.encoding 读取文件的编码，默认是 utf8
• opts.destination 生成文档的路径，默认是 ./out/
• opts.recurse 运行时是否递归子目录
• opts.verbose 运行时是否输出详细信息，默认是 false

2.3 主题及模板

1、JSDoc默认的主题有点凌乱，可以通过安装新的主题来配置.常见主题有docdash、minami

# 安装
npm install docdash -D

# 在jsdoc.json中配置
{
  "opts" :{
    "template":"node_modeules/docdash
  }
}

2、如果主题不满意还可以用自己的模板

{
  "templates": {
    "cleverLinks": true,
    "default": {
      "layoutFile": "plugins/layout.tmpl"
    }
  }
}