JSDoc：如何避免属性/吸气剂的重复文档？答案

【问题标题】：JSDoc: How to avoid duplicate documentation for properties/getters?JSDoc：如何避免属性/吸气剂的重复文档？
【发布时间】：2015-05-05 07:28:33
【问题描述】：

我目前正在使用 JSDoc 记录我的一个 API。虽然这很好用，但真正让我烦恼的一件事是重复文档的出现。一个常见的例子是属性及其 getter 的文档：

function AClass() {
    /**
     * The current state of the object. Determines wether this object has been initialized yet.
     * @type {String}
     * @private
     */
    this._state = "initalized";
}

/**
 * Returns the current state of the object, which determines if the object has been initalized yet.
 * @return {String} The current state of the object
 */
AnObject.prototype.getState = function() {
    return this._state;
}

我想每个人都在这里看到了这个问题。该属性实际上记录了 3 次（私有属性本身、getter 方法描述和方法的返回值）。简单地将方法的描述更改为 Returns the state 之类的东西并不是一个真正的选择，因为我通常在文档输出中隐藏私有属性。

我对此类情况是否有最佳实践以及其他人如何处理这件事很感兴趣。作为一个痴迷于 DRY 的人，似乎应该有更好的选择来处理这些情况。

【问题讨论】：

标签： javascript documentation documentation-generation jsdoc jsdoc3

【解决方案1】：

我也注意到了这一点并同意这有点烦人，同时我认为没有完美的解决方案。

你可能会做的事情是这样的

/**
 * Getter for {@link AClass._state}
 * @return {String} Returns {@link AClass._state}
 */

【讨论】：