Question

我应该做这样的事情吗？

/**
* Constructor function
*
* @contructor
* @param {Number} x - a number.
*/
function foo(x){
    this.x = x;
    /**
     * Sum to x.
     * @param {Number} y - A number.
     * @param {Object} this - The bar.
     * @param {Number} this.x - A number [requered].
     */
    this.bar(y) {
        return this.x + y;
    }
}

或者在这种情况下，我不应该在注释中定义this.x的必需定义。

Answer 1

在记录代码时，您不应向外部“公开”方法的内部内容。只需正确正确地记录您的方法，什么方法就可以：

确实
接受（如果有）
并返回（如果有）

...简洁明了。

但是，如果要记录对象的内部结构，可以使用@private或@protected标签。

JSDoc tags as "accessibility modifiers"

更多类似的内容：

/**
 * Constructs foo, that does something useful.
 *
 * @contructor
 * @param {number} x - A number, which determines X.
 */
function foo(x){
    /*
     * An important number.
     *
     * @private
     * @type {number}
     */
    this._x = x;        

    /**
     * Returns the summary of X and Y.
     *
     * @param {number} y - A number to add to X.
     * @returns {number} The summary of X and Y.
     */
    this.bar(y){
        return this._x + y;
    }
}

这样，当您使用类型检查器或IDE时，如果您忽略了必需的参数，则会收到通知。

JavaScript文档选项：

JSDoc
ESDoc

对于键入的JavaScript，请检出：

Usage of JSDoc

如何记录JSDoc方法所需的变量？

1 个答案: