JSDoc

JSDoc 是一个增强代码的注释系统（注释规范），可以增强代码的可读性。
通过注释，还可以导出一个比较规范的API文档。下面就介绍一下常见的几种注释，以及使用场景。

基本注释

/**
 * content
 */

这就是最基本的注释形式，相信大家也很常用。
每一行的 * 对齐，内容行的 * 与内容有一个空格。

常用标签注释

1. @alias 函数与变量别名

这个注释使用的场景不是很多，下面是两个使用的场景。

;(function () {
  /**
   * @alias test
   */
  function test1 () {}

  window.test = test1;
})();

function test (a) {
  a += 1;

  return function () {
    return a * a;
  }
}

/**
 * @alias test1 - test
 */
const test1 = test(5);
test1();

2. @contructor 构造函数

构造函数的注释，可以使用在原生的对象和ES6的构造器上。

;(function () {

  /**
   * @constructor Test
   */
  var Test = function () {

  }

  window.Test = Test;
});

const test1 = new Test();

class Test {

  /**
   * @constructor Test
   * 
   */
  constructor (a, b) {

  }
}

3. @description 描述

描述信息注释，常用于描述函数功能或者描述某段代码块的功能。

/**
 * @description 这是一个HTML模板替换函数
 */
function tplReplace (tmp, rep) {

  /**
   * @description 内容描述
   */
  xxxxx2q1e121e21
}

4. @example 例子

编写案例时，可以使用。

/**
 * @example 
 *  var t = new Test(1, 2);
 *  t.plus(); // 1 + 2 的结果
 */
function Test (a, b) {
  this.a = a;
  this.b = b;
}

Test.prototype.plus = function () {
  return this.a + this.b;
}

5. @extends 继承关系

常用于类继承时使用，react开发中非常常见。

import React, { Component } from 'react';

/**
 * @extends {React.component}
 */
class Test extends Component {

}

export default Test;

6. @params 参数

描述函数的形参。

/**
 * @description 这是一个做加法运算的函数
 * @param {number} a - 加法中的第一个数字
 * @param {number} b - 加法中的第二个数字
 */
function test (a, b) {
  return a + b;
} 

param 可以标注的类型。

number string boolean function undefined
object Array Object Null

7. @property 属性

属性配置项，作为某个插件或者某个功能体的参数说明。

/**
 * @property {string} type - 轮播图类型
 *  slide(default)：无缝轮播
 *  fade：淡入淡出
 * @property {number} duration - 轮播图轮播等待时间
 * @property {boolean} autoplay - 是否设置自动轮播
 *  true：加载后自动轮播
 *  false：加载后手动切换
 */
var obj = {
  type: 'slide',
  duration: 3000,
  autoplay: true
}

8. @return 返回值

函数返回值。无返回值是可以写 void。

/**
 * @description 这是一个做加法运算的函数
 * @param {number} a 第一个数字
 * @param {number} b 第二个数字
 * @return {number}
 */
function test (a, b) {
  return a + b;
}

9. @type 变量类型

描述声明变量的类型。

/**
 * @type {number} a - xxx
 * @type {string} b - xxx
 * @type {boolean} c - xxx
 * @type {function} d - xxx
 */
var a = 1,
    b = '2',
    c = true,
    d = function () {};

如果结构比较复杂的参数，可以这样使用。

/**
 * @type {Array.<number>} arr - xxx
 * @type {number[]} arr - xxx
 */
const arr = [1, 2, 3, 4, 5];

/**
 * @type {Array.<object>} arr - xxx
 * @type {Object[]} arr - xxx
 */
const arr = [
  {},
  {}
]

10. @module 模块

表明某个模块属于哪个页面，或者可以被哪一个页面引用。
如果是通用的模块，可以使用Common（大小写任意，建议大写）。

/**
 * @module IndexPage/test
 * @module ListPage/test
 * @description xxx
 * @param {string} a - xxx
 * @param {number} b - xxx
 */
export default function (a, b) {

}

/**
 * @module Common/test
 * @description xxx
 * @param {string} a - xxx
 * @param {number} b - xxx
 */
export default function (a, b) {

}

11. @access 访问等级 主要针对于类

priavte 私有
protected 受保护的
public 公有

这种注释不是很常用。

class Test {
  /** @access private a - xxx */
  #a = 0;
  
  constructor () {
     /**
      * @access protected b - xxx
      * @access public c - xxx
      */
    this._b = 1;
    this.c = 2;
  }
}

class Test {
  /** @private a - xxx */
  #a = 0;
  
  constructor () {
     /**
      * @protected b - xxx
      * @public c - xxx
      */
    this._b = 1;
    this.c = 2;
  }
}

12. @author 作者

顾名思义，描述作者的信息，主要包括作者名称和邮箱地址。

/**
 * @author yueluo <yueluo.yang@qq.com>
 */

13. @borrows 改变标识符

不常用。

const test1 = '123';

/**
 * @borrows test1 as test
 */
var obj = {
  test: test1
}

14. @callback 回调函数

回调函数的注解。

function Test () {}
/**
 * @param {Test~testCallback} cb
 */
Test.prototype.a = function (cb) {
  cb();
}

/**
 * @callback Test~testCallback
 */
function b () {

}

/**
 * @param {test~testCallback} cb - xxx 
 */
function test (cb) {
  cb();
}

15. @class 类

这是就比较常用。

/**
 * @class Test - xxx
 * @classdesc xxxx
 */
class Test {
  
}

16. @constant 常量

声明常量时，可以使用。

/**
 * @constant {string}
 * @description xxx
 */
const TEST = 'xxx';

/**
 * @constant {Object}
 * @description xxx
 * 
 * @property {string} BASE_URL xxx
 * @property {string} GET_COURSE_DATA xxx
 */
const API = {
  BASE_URL: 'xxx',
  GET_COURSE_DATA: 'xxx'
}

17. @file 文件描述、@copyright 版权描述

每一个文件的最上方都应该有文件描述。

/**
 * @file xxx
 * @copyright xxx
 */

18. @requires 依赖模块

导入模块时，对模块进行注释。

/**
 * @requires node_modules/html-webpack-plugin
 * @description xxx
 */
const HtmlWebpackPlugin = require('html-webpack-plugin');

19. @see 指明文档位置

定义两个同名的方法时，可以使用，感觉意义不大。

/**
 * @description 加法运算
 * @param {number} a - 加法运算的第一个值
 * @param {number} b - 加法运算的第二个值
 */
function sum (a, b) {
  console.log(a + b);
}

/**
 * @see sum
 */
function sum (a, b) {

}

20. @summary 总结描述

可以描述某段代码块的作用。不常用。

function test () {
  /**
   * xxxxxx
   * @summary
   */
  xxx
}

21. @verson 版本

一般来说都是在文件最上方，对于模块和插件来说比较重要。

/**
 * @file xxx
 * @version 0.1.0
 */

常见的注释案例

1. 文件头注释

/**
 * @file 轮播图插件
 * @author yueluo <yueluo.yang@qq.com>
 * @version 0.1.0
 * @time 2020-05-16 17:12
 */

JSDoc中不存在时间的注释规范，可以使用@dateTime或者@time标准。
个人比较喜欢用@time，感觉比较简便。

2. class 注释

/**
 * @class 轮播图插件
 * @module IndexPage/Croousel
 * @description xxx
 */ 

3. 方法注释

/**
 * HTML模板替换
 * 
 * @param {function} template - HTML字符串模板
 * @param {object} replaceObject - 要替换的字段
 * @return {string} html - 模板变量被替换后的HTML字符串
 * @description xxxx
 */
function tplReplace (template, replaceObject) {
  return template().replace(/{{(.*?)}}/g, (node, key) => {
    return replaceObject[key];
  });
}

4. 模块注释

/**
 * @module 选项卡模块
 * @description xxx
 */

JS 注释大概分为以下几种场景。

头注释、导入的模块的注释、工具函数注释、模块注释、类注释
方法注释、函数内部功能描述、代码注释、变量注释、数据注释

总结

本文介绍JSDoc中比较常见的几种注释，开发中可以有意识的去应用它。
下面是我编写的工具函数，在其中是否能你是否感觉到注释存在的意义。
可能你会说，开发时间已经很赶了，还要编写注释，太影响效率啦。
我想说的是，要是你想成为合格的工程师，就必须对自己严格一些（个人建议）。

/**
 * @file 工具函数
 * @module libs/util
 * @version 0.1.0
 * @author yueluo <yueluo.yang@qq.com>
 * @time 2020-06-04
 */

/**
 * @description 对象转表单格式字符串
 * @param {object} obj - 需要转化的对象
 * @return {string} 转换后的字符串
 */
function formatData (obj) {
  let str = '';
  for (const key in obj) {
    str += `${key}=${obj[key]}&`;
  }
  return str.replace(/&$/, '');
}

/**
 * @description 获取当天24点的时间戳
 * @return {number} 时间戳
 */
function get_24_stmp () {
  return new Date().setHours(0, 0, 0, 0) + (60 * 60 * 24 * 1000 - 1);
}

/**
 * @description 获取当前的时间戳
 * @return {number} 时间戳
 */
function get_now_stmp () {
  return new Date().getTime();
}

// 导出工具函数集合
module.exports = {
  formatData,
  get_24_stmp,
  get_now_stmp
}