Question

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

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;
}

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

我感兴趣的是，如果有这种情况的最佳做法以及其他人如何处理这种情况。作为一个痴迷于干的家伙，似乎应该有一个更好的选择来处理这些案件。

Answer 1

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

你可能会做什么就像

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

JSDoc：如何避免属性/ getter的重复文档？

1 个答案: