该文档是否正确？（Yes/No 答案对我来说足够了）

Question

我真的很困惑我应该如何记录这三种方法（onKick、offKick、triggerKick）：

var events = $( {} ); // jQuery Pub/Sub .

/**
 * Creates a football player .
 * @constructor
 */
function Player() {
 ...
}

Player.prototype = {
    ...,
    /**
     * Subscribes a function to the kick event .
     * @param  {Function} fn An event handler .
     */
    onKick: function( fn ) {
        events.on('kick.FootballGame', fn);
    },

    /**
     * Unsubscribes a function from the kick event .
     * @param  {Function} fn The event handler .
     */
    offKick: function( fn ) {
        events.off('kick.FootballGame', fn);
    },

    /**
     * Kicks the ball .
     * @fires kick.FootballGame
     */
    triggerKick: function() {
        events.trigger('kick.FootballGame');
    },
    ...
};

这份文件是否正确？ Yes/No 将不胜感激。

谢谢。

Answer 1

我会说你接近 well-documented 脚本块。我会提出一些更改，如您的代码所示：

/**
 * Creates an new Football Player.
 * @constructor
 */
function Player() {
 ...
}

Player.prototype = {

    /**
     * Subscribes a function to the kick event.
     * @param {function} fn - an event handler.
     */
    onKick: function( fn ) {
        events.on('kick.FootballGame', fn);
    },

    ...
};

一般规则：

行中最后一个字和点之间没有空格
单词之间不能超过一个空格
用破折号分隔参数及其用途
遵循变量类型的大小写（如果适用），即 {function} 而不是 {Function}

该文档是否正确？（Yes/No 答案对我来说足够了）

Is this documentation correct?( Yes/No answer is enough for me )

javascript

jsdoc

jsdoc3

这份文件是否正确？ Yes/No 将不胜感激。