我目前正在使用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;
}
我想每个人都看到了这里的问题。该属性实际上被记录了三次(私有属性本身、getter方法描述和方法的返回值)。简单地将方法的描述更改为类似Returns the state
的内容并不是一个真正的选项,因为我通常会在文档输出中隐藏私有属性。
我感兴趣的是,对于此类案件,是否有最佳实践,以及其他人如何处理。作为一个痴迷于DRY的人,似乎应该有更好的选择来处理这些案件。
我也注意到了这一点,并同意这有点烦人,同时我认为没有完美的解决方案。
你可能会做一些类似的事情
/**
* Getter for {@link AClass._state}
* @return {String} Returns {@link AClass._state}
*/
刚刚遇到这个问题,我想提到我在这些情况下使用@see。