Javascriptコメント仕様

Javascriptコードの注釈仕様
一、文法
1.コメントの説明
文法:コメントブロックの最初の行に書きます.

/**
 * events-function(       )
 * @description         （  /  ）
 */
togglePlay: function() {
    //       ...
}

2.ラベル
文法:@tagName

/** @function */
function fn() {

}

3.ラベルの説明
文法:-説明テキスト

/**
 * @constructor Student -   
 * @param {string} name -      
 */
 function Student(name) {
     
 }

4.タイプ
文法:{typeName}(ラベルと組み合わせて使うことができます.例えば@param)

/**
 * @param {string} a     
 */
function fn(a, b, c) {

}

5.オプションパラメータ
文法:[paramName](ラベルと組み合わせて使用できます.例えば@param)

/**
 *  @param {string} a     
 *  @param {number} [b]     
 */
function fn(a, b) {

}

6.パラメータにはデフォルトがあります.
文法:[paramName=value](ラベルと組み合わせて使用できます.例えば@param)

/**
 *  @param {string} a     
 *  @param {number} [c=666]       
 */
function fn(a, c) {

}

7.リンク
文法:[link text]{@link namepathOr URL}

/**
 * See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
 * Also, check out {@link http://www.google.com|Google} and
 * {@link https://github.com GitHub}.
 */

二、例
1.関数

/**
 *             
 * @function _str2time
 * @param strTime {String} - e.g "2017-02-13 10:02:58" or "2017-02-13" or "9:10"
 * @param type {String} - e.g date, dateTime, time
 */
function _str2time(strTime, type) {
    //       
}

2.クラス/コンストラクター

/**
 *    
 * @class Timer
 */

function Timer() {
    this._timeId = 0;
    this._eventId = -1;

    this.eventHandler = {
        'stop': {}
    };

    /**
     *            
     * @memberof Timer
     * @member stopped
     * @instance
     */
    this.stopped = true;

    /**
     *      
     * @memberof Timer
     * @instance
     * @method start
     * @param {function} handler -              
     * @param {number} interval -           
     */
    this.start = function (handler, interval) {
        this.stopped = false;
        let _recursion = function() {
            this._timeId = setTimeout(() => {
                handler()
                    .then(() => {
                        if (this.stopped) {
                            clearTimeout(this._timeId);
                            this._trigger('stop');
                            return;
                        }
                        _recursion();
                    })
                    .catch(err => {
                        clearTimeout(this._timeId);
                        this.stopped = true;
                        this._trigger('stop');
                        if (err) throw new Error(err);
                    });
            }, interval)
        }.bind(this);
        _recursion();
    }

    /**
     *      
     * @memberof Timer
     * @instance
     * @method stop
     */
    this.stop = function () {
        this.stopped = true;
    }
}

/**
 *     
 * @memberof Timer
 * @instance
 * @method on
 * @param {string} type -       e.g 'stop'
 * @param {function} fn -       
 * @return {number} eventId -       Id，      
 */
Timer.prototype.on = function (type, fn) {
    let _eventId = fn.name || ++this._eventId;
    this.eventHandler[type][_eventId] = fn;
    return _eventId;
}

/**
 *     
 * @private
 */
Timer.prototype._trigger = function (type) {
    let handlerMap = this.eventHandler[type];
    for (let key in handlerMap) {
        handlerMap[key]();
    }
}

/**
 *       
 * @memberof Timer
 * @instance
 * @method off
 * @param {string} type -       e.g 'stop'
 * @param {function} target -       Id      
 */
Timer.prototype.off = function (type, target) {
    let _target = (typeof target === 'function') ? target.name : target;
    delete this.eventHandler[type][_target];
}