行内注释

  1. 显示一个解释的评论

    // 用来显示一个解释的评论

  2. 显示表达式的结果

    // -> 用来显示表达式的结果

  3. 显示 console 的输出结果

    // >用来显示 console 的输出结果

示例

1
2
3
4
5
function test() {
  // 测试函数
  console.log('Hello World!') // >Hello World!
  return 3 + 2 // ->5
}

//(双斜线)与代码之间保留一个空格，并且//(双斜线)与注释文字之间保留一个空格。

单行注释

示例

1
2
// 调用了一个函数；1)单独在一行
setTitle()

单独一行：//(双斜线)与注释文字之间保留一个空格。

普通多行注释

示例

1
2
3
4
5
/*
 * 代码执行到这里后会调用setTitle()函数
 * setTitle()：设置title的值
 */
setTitle()

若开始/*和结束*/都在一行，推荐采用单行注释。若至少三行注释时，第一行为/*，最后行为*/，其他行以*开始，并且注释文字与*保留一个空格。

函数多行注释

函数(方法)注释也是多行注释的一种，但是包含了特殊的注释要求，参照 JSDoc。

以下字段并不是全部，全部请参考JSDoc 中文文档或JSDoc 中文文档

常用注释关键字

注释名语法含义示例
@param@param 参数名 {参数类型} 描述信息描述参数的信息@param name {String} 传入名称
@return@return {返回类型} 描述信息描述返回值的信息@return {Boolean} true:可执行;false:不可执行
@author@author 作者信息 [附属信息：如邮箱、日期]描述此函数作者的信息@author 张三 2015/07/21
@version@version XX.XX.XX描述此函数的版本号@version 1.0.3
@example@example 示例代码演示函数的使用@example setTitle(‘测试’)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/**
 * 合并Grid的行
 * @param grid {Ext.Grid.Panel} 需要合并的Grid
 * @param cols {Array} 需要合并列的Index(序号)数组；从0开始计数，序号也包含。
 * @param isAllSome {Boolean} ：是否2个tr的cols必须完成一样才能进行合并。true：完成一样；false(默认)：不完全一样
 * @return void
 * @author polk6 2015/07/21
 * @example
 * _________________                             _________________
 * |  年龄 |  姓名 |                             |  年龄 |  姓名 |
 * -----------------      mergeCells(grid,[0])   -----------------
 * |  18   |  张三 |              =>             |       |  张三 |
 * -----------------                             -  18   ---------
 * |  18   |  王五 |                             |       |  王五 |
 * -----------------                             -----------------
 */
function mergeCells(
  grid: Ext.Grid.Panel,
  cols: Number[],
  isAllSome: boolean = false
) {
  // Do Something
}

文档注释

文档注释将会以预定格式出现在 API 文档中。它以“/\**”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。

文档注释必须包含一个或多个注释标签。

  1. @module。声明模块

    1
    2
    3
    4
    /**
     * 模块说明
     * @module 模块名
     */
    1
    2
    3
    4
    /**
     * Core模块提供最基础、最核心的接口
     * @module Core
     */

  2. @class。声明类

    1
    2
    3
    4
    5
    /**
     * 类说明
     * @class 类名
     * @constructor
     */

    @class 必须搭配@constructor 或@static 使用，分别标记非静态类与静态类。

    1
    2
    3
    4
    5
    6
    /**
     * 节点集合类
     * @class NodeList
     * @constructor
     * @param {ArrayLike<Element>} nodes 初始化节点
     */

  3. @method。声明函数或类方法

    1
    2
    3
    4
    5
    6
    7
    /**
     * 方法说明
     * @method 方法名
     * @for 所属类名
     * @param {参数类型} 参数名 参数说明
     * @return {返回值类型} 返回值说明
     */

    没有指定@for 时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加@static；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。

    1
    2
    3
    4
    5
    6
    7
    /**
     * 返回当前集合中指定位置的元素
     * @method
     * @for NodeList
     * @param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数
     * @return {Element} 指定元素
     */

  4. @param。声明函数参数，必须与@method 搭配使用。

  5. @property。声明类属性

    1
    2
    3
    4
    /**
     * 属性说明
     * @property {属性类型} 属性名
     */

注意事项

应该做的

  1. 总是在单行注释符后留一个空格。

    1
    // this is comment

  2. 总是在多行注释的结束符前留一个空格（使星号对齐）

    1
    2
    3
    /*
                                 
     */

  3. 如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。

    1
    2
    3
    4
    // TODO 未处理IE6-8的兼容性
    function setOpacity(node, val) {
      node.style.opacity = val
    }

不该做的

  1. 不要把注释写在多行注释的开始符、结束符所在行。

    1
    2
    3
    /* start
                                 
    end */
    1
    2
    3
    4
    /*
    here is line 1
    here is line 2
     */

  2. 不要编写无意义的注释。

    1
    2
    // 初始化value变量为0
    var value = 0

注释示例

参数和返回值类型 Type：string、boolean、number、object、array、function

基本方法块注释

如果描述不能描述清楚，添加例子来描述。

1
2
3
4
5
6
7
8
9
/**
 * @method
 * @param {Type} data 目标对象
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data) {
  return '返回对象'
}

基本方法块注释-注释过长时

如果需要折行则在文本中使用<br/>标签

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * @method
 * @param {Type} data 目标对象<br/>
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data) {
  return '返回对象'
}

基本方法块注释-参数可选

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * @method
 * @param {Type} [data] 目标对象
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data) {
  return '返回对象'
}

基本方法块注释-带默认值

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * @method
 * @param {Type} data={} 目标对象
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data) {
  return '返回对象'
}

方法块注释特殊参数

如果描述不能描述清楚，添加例子来描述。
如果方法中有异常处理，标记异常处理注释

1
2
3
4
5
6
7
8
9
10
11
12
/**
 * @method
 * @param {Type} data 目标对象
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 * @throws {string} 抛出'Error'异常
 * @example
 * add(1, 2);    // 返回3
 */
function matchedNumber(data) {
  return '返回对象'
}

如果有返回值增加@returns 如果没有省略此属性

文件注释

在文件头部增加文件注释

1
2
3
4
5
6
/**
 * @file LBS控制器
 * @author limingle
 * @copyright Synway SFE
 * @createDate 2017-10-16 09:40:11
 */

变量注释

将关键的变量进行特殊注释，生成到文档中

1
2
3
4
5
6
7
8
9
10
/**
 * @var {object}
 * @desc 变量定义
 * @property {string} a 属性a
 * @property {string} b 属性b
 */
var foo = {
  a: 'a',
  b: 'b'
}

常量注释

将关键常量进行特殊注释，生成到文档中，如果有默认值增加@default属性

1
2
3
4
5
6
/**
 * @constant {string}
 * @default #000
 * @desc 常量定义
 */
const COLOR_WHITE = '#fff'

枚举注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/**
 * @enum {number}
 * @desc cgi常见的返回码
 */
var RETCODE = {
  /**
   * @desc 未登录
   */
  NOT_LOGIN: 100000,
  /**
   * @desc 参数错误
   */
  PARAM_ERROR: 100001,
  /**
   * @type {string}
   * @desc 未知错误
   */
  UNKOWN_ERROR: 'unkown'
}

类的注释

默认情况先一个 function 就是一个类，ES6 中使用 Class 来表示一个类
我们项目中使用 class.js 来实现类，在我们项目中使用类注释时需要在@class后边增加类名，不然 jsdoc 无法自动识别类名

1
2
3
4
5
6
7
8
/**
 * @class
 * @classdesc 这是对myClass类的描述
 * @desc 这是对myClass类的构造函数的描述
 */
function myClass() {
    ...
}
1
2
3
4
5
6
/**
 * @class LBSControllerCom
 * @classdesc LBS控制类
 * @desc 初始化ws
 */
var LBSControllerCom = Com.extends({})

类的属性

类的属性和变量都会生成到 jsdoc 文档的 Member 模块中，在类中使用属性标识

1
2
3
4
5
6
7
8
var LBSControllerCom = Com.extends({
  /**
   * @member {string}
   * @desc 这样标识类的属性
   */
  foo1: 'a',
  init: function () {}
})

webstorm 的 live Templates

  1. desc

    1
    2
    3
    4
    5
    /**
     * @description:
     * @author: xiaokang
     * @time: $date$
     */

    image-20200625174405983

  2. fun

    1
    2
    3
    4
    5
    6
    7
    8
    /**
     * @func
     * @desc 函数的描述
     * @param {参数1的类型} 参数名 参数描述
     * @param {参数1的类型} 参数名=1 默认值参数
     * @param {参数1的类型} [参数名] 可选参数
     * @returns {Type} 函数返回值的描述
     */

    示例

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    /**
     * @func
     * @desc 这个函数用于测试
     * @param {string} a 第一个参数
     * @param {number} b=1 第二个参数
     * @param {number} [c=2] 可选参数
     * @returns {boolean} 返回值
     */
    function f(a, b = 1, c = 2) {
      return true
    }

    image-20200625175556046

  3. method

    1
    2
    3
    4
    5
    6
    7
    8
    /**
     * @method
     * @desc 根据目标对象获取运营商
     * @param {参数1的类型} 参数名 参数描述
     * @param {参数1的类型} 参数名=1 默认值参数
     * @param {参数1的类型} [参数名] 可选参数
     * @returns {Type} 函数返回值的描述
     */
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    /**
     * @class
     * @classdesc 这是对myClass类的描述
     */
    function myClass() {}

    /**
     * @method
     * @desc myClass方法的描述
     * @param {string} a - 参数a
     */
    myClass.prototype.foo = function (a) {
      console.log('xiaokang')
      return true
    }

    image-20200625175943579

  4. vari

    1
    2
    3
    4
    5
    6
    /**
     * @var {object}
     * @desc 变量定义
     * @property {string} a 属性a
     * @property {string} b 属性b
     */

    示例

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    /**
     * @var foo
     * @desc 变量定义
     * @property {string} a 属性a
     * @property {string} b 属性b
     */
    var foo = {
      a: 'a',
      b: 'b'
    }

    image-20200625175042098

文章参考

  1. JavaScript 开发规范（一）： 命名与注释规范详解
  2. 《Airbnb JavaScript Style Guide 中文版》
  3. js/javascript 代码注释规范与示例
  4. Javascript 注释规范
  5. jsdoc
  6. 小康的 jsdoc