如何使用 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 标记为"辅助功能修饰符">

---

更多像这样：

/**
* 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，请查看：

• 流
• 打字稿

---

JSDoc 的用法