JSDoc规范

js注释规范基于jsdoc，写出的代码注释能够成功生成注释文档。

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

文件注释

在文件头部增加文件注释

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

变量注释

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

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

常量注释

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

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

方法注释

基本方法块注释

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

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

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

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

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

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

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

方法块注释特殊参数

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

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

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

类的注释

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

1 /**
2  * @class
3  * @classdesc 这是对myClass类的描述
4  * @desc 这是对myClass类的构造函数的描述
5  */
6 function myClass() {
7     ...
8 }

或者

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

类的属性

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

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

枚举注释

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

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

参考链接： JSDoc 3