行内注释
-
显示一个解释的评论
// 用来显示一个解释的评论 -
显示表达式的结果
// -> 用来显示表达式的结果 -
显示 console 的输出结果
// >用来显示 console 的输出结果
示例
function test() { // 测试函数
console.log('Hello World!'); // >Hello World!
return 3 + 2; // ->5
}
//(双斜线)与代码之间保留一个空格，并且//(双斜线)与注释文字之间保留一个空格。
单行注释
示例
// 调用了一个函数；1)单独在一行
setTitle();
单独一行：//(双斜线)与注释文字之间保留一个空格。
普通多行注释
示例
/*
* 代码执行到这里后会调用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(‘测试’) |
/**
* 合并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文档中。它以“/\**”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。
文档注释必须包含一个或多个注释标签。
-
@module。声明模块
/** * 模块说明 * @module 模块名 *//** * Core模块提供最基础、最核心的接口 * @module Core */ -
@class。声明类
/** * 类说明 * @class 类名 * @constructor */@class必须搭配@constructor或@static使用，分别标记非静态类与静态类。
/** * 节点集合类 * @class NodeList * @constructor * @param {ArrayLike<Element>} nodes 初始化节点 */ -
@method。声明函数或类方法
/** * 方法说明 * @method 方法名 * @for 所属类名 * @param {参数类型} 参数名 参数说明 * @return {返回值类型} 返回值说明 */没有指定@for时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加@static；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。
/** * 返回当前集合中指定位置的元素 * @method * @for NodeList * @param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数 * @return {Element} 指定元素 */ -
@param。声明函数参数，必须与@method搭配使用。
-
@property。声明类属性
/** * 属性说明 * @property {属性类型} 属性名 */
注意事项
应该做的
-
总是在单行注释符后留一个空格。
// this is comment -
总是在多行注释的结束符前留一个空格（使星号对齐）
/* */ -
如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。
// TODO 未处理IE6-8的兼容性 function setOpacity(node, val) { node.style.opacity = val; }
不该做的
-
不要把注释写在多行注释的开始符、结束符所在行。
/* start end *//* here is line 1 here is line 2 */ -
不要编写无意义的注释。
// 初始化value变量为0 var value = 0;
注释示例
参数和返回值类型Type：string、boolean、number、object、array、function
基本方法块注释
如果描述不能描述清楚，添加例子来描述。
/**
* @method
* @param {Type} data 目标对象
* @returns {Type} 运营商名称
* @desc 根据目标对象获取运营商
*/
function matchedNumber(data){
return '返回对象'
}
基本方法块注释-注释过长时
如果需要折行则在文本中使用<br/>标签
/**
* @method
* @param {Type} data 目标对象<br/>
* 例：
* {
* 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 如果没有省略此属性
文件注释
在文件头部增加文件注释
/**
* @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';
枚举注释
/**
* @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() {}
})
webstorm的live Templates
-
desc
/** * @description: * @author: xiaokang * @time: $date$ */ -
fun
/** * @func * @desc 函数的描述 * @param {参数1的类型} 参数名 参数描述 * @param {参数1的类型} 参数名=1 默认值参数 * @param {参数1的类型} [参数名] 可选参数 * @returns {Type} 函数返回值的描述 */示例
/** * @func * @desc 这个函数用于测试 * @param {string} a 第一个参数 * @param {number} b=1 第二个参数 * @param {number} [c=2] 可选参数 * @returns {boolean} 返回值 */ function f(a, b = 1, c = 2) { return true } -
method
/** * @method * @desc 根据目标对象获取运营商 * @param {参数1的类型} 参数名 参数描述 * @param {参数1的类型} 参数名=1 默认值参数 * @param {参数1的类型} [参数名] 可选参数 * @returns {Type} 函数返回值的描述 *//** * @class * @classdesc 这是对myClass类的描述 */ function myClass() { } /** * @method * @desc myClass方法的描述 * @param {string} a - 参数a */ myClass.prototype.foo = function (a) { console.log('xiaokang') return true } -
vari
/** * @var {object} * @desc 变量定义 * @property {string} a 属性a * @property {string} b 属性b */示例
/** * @var foo * @desc 变量定义 * @property {string} a 属性a * @property {string} b 属性b */ var foo = { a:'a', b:'b' }