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