javascript - 如何使用 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

在编写代码文档时，您不应向“外部”透露您的方法的内部结构。只需正确、正确地记录您的方法，每种方法是什么:

• 做
• 接受(如果有的话)
• 并返回(如果有的话)

...以简洁的形式。

但如果您想记录对象的内部结构，可以使用 @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，查看:

• flow
• TypeScript

---

Usage of JSDoc