最近查看代码,看其他人的代码确实很让人头疼,由于没有任何注释规范,导致代码里很少有注释,或者注释写的很简练,今天对于注释规范进行总结。
js注释规范基于jsdoc,写出的代码注释能够成功生成注释文档。
由于jsdoc的规范太多,为了项目的可用性,对jsdoc的某些属性进行提取形成文档,供开发人员使用。
方法注释
基本方法块注释
如果描述不能描述清楚,添加例子来描述。
/**
* @method
* @param {Type} data 目标对象
* @returns {Type} 运营商名称
* @desc 根据目标对象获取运营商
*/
function matchedNumber(data){
return '返回对象'
}
基本方法块注释,注释过长
/**
* @method
* @param {Type} data 目标对象<br/>
* 例:
* {
* target:手机号
* }
* @returns {Type} 运营商名称
* @desc 根据目标对象获取运营商
*/
function matchedNumber(data){
return '返回对象'
}
如果需要折行则在文本中使用<br/>
标签
基本方法块注释,参数可选
/**
* @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