JSDoc規范

js注釋規范基於jsdoc，寫出的代碼注釋能夠成功生成注釋文檔。 

參數和返回值類型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';

方法注釋

基本方法塊注釋

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

/**
 * @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 '返回對象'
}

方法塊注釋特殊參數

如果描述不能描述清楚，添加例子來描述。 
如果方法中有異常處理，標記異常處理注釋

如果有返回值增加@returns 如果沒有省略此屬性 

/**
 * @method
 * @param {Type} data 目標對象
 * @returns {Type} 運營商名稱
 * @desc 根據目標對象獲取運營商
 * @throws {string} 拋出'Error'異常
 * @example
 * add(1, 2);    // 返回3
 */
function matchedNumber(data){
    return '返回對象'
}

類的注釋

默認情況先一個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() {}
})

枚舉注釋

用於url列表或者顏色枚舉值，一般用於配置文件中

/**
 * @enum {number}
 * @desc cgi常見的返回碼
 */
var RETCODE = {
    /**
     * @desc 未登錄
     */
    NOT_LOGIN: 100000,
    /**
     * @desc 參數錯誤
     */
    PARAM_ERROR: 100001,
    /**
     * @type {string}
     * @desc 未知錯誤
     */
    UNKOWN_ERROR: 'unkown'
}

參考鏈接： JSDoc 3