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

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

当您记录您的代码时，您不应该向 "outside" 透露您的方法的内部结构。只需正确、正确地记录您的方法，每种方法是什么：

会
接受（如果有）
和returns（如果有的话）

...简洁的形式。

但是如果您想记录对象的内部结构，可以使用 @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 记录方法所需的变量？

How can I document a variable required by a method with JSDoc?

javascript

jsdoc