Javascript注释规范

最近查看代码，看其他人的代码确实很让人头疼，由于没有任何注释规范，导致代码里很少有注释，或者注释写的很简练，今天对于注释规范进行总结。
js注释规范基于jsdoc，写出的代码注释能够成功生成注释文档。
由于jsdoc的规范太多，为了项目的可用性，对jsdoc的某些属性进行提取形成文档，供开发人员使用。

方法注释

基本方法块注释

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

/**
 * @method
 * @param {Type} data 目标对象
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

基本方法块注释，注释过长

/**
 * @method
 * @param {Type} data 目标对象

 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

如果需要折行则在文本中使用
标签

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

/**
 * @method
 * @param {Type} [data] 目标对象
 * 例：
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

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

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

方法块注释特殊参数

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

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

如果有返回值增加@returns 如果没有省略此属性
参数和返回值类型Type：string、boolean、number、object、array、function

文件注释

在文件头部增加文件注释

/**
 * @file LBS控制器
 * @author limingle
 * @copyright Synway SFE
 * @createDate 2017-10-16 09:40:11
 */

变量注释

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

/**
 * @var {object}
 * @desc 变量定义
 * @property {string} a 属性a
 * @property {string} b 属性b
 */
var foo = {
    a: 'a',
    b: 'b'
}

常量注释

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

/**
 * @constant {string}
 * @default #000
 * @desc 常量定义
 */
const COLOR_WHITE = '#fff';

枚举注释

用于url列表或者颜色枚举值，一般用于配置文件中

/**
 * @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无法自动识别类名

/**
 * @class
 * @classdesc 这是对myClass类的描述
 * @desc 这是对myClass类的构造函数的描述
 */
function myClass() {
    ...
}

或者

/**
 * @class LBSControllerCom
 * @classdesc LBS控制类
 * @desc 初始化ws
 */
var LBSControllerCom = Com.extends({})

类的属性

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

var LBSControllerCom = Com.extends({
    /**
     * @member {string}
     * @desc 这样标识类的属性
     */
    foo1 : 'a',
    init: function() {}
})

---

参考链接：
JSDoc Guide