JSDoc: How to avoid duplicate documentation for properties/getters?

Question

I am currently documenting one of my APIs using JSDoc. Although this works well, one thing that really annoys me is the occurence of duplicate documentation. One common example of this is the documentation of a property and its 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;
}

I suppose everyone sees the issue here. The property is actually documented three times (the private property itself, the getter method description and the method's return value). Simply changing the method's description to something like Returns the state is not really an option, since I generally hide private properties in the documentation output.

I am interested in if there is a best practice for such cases and how others handle this. As a DRY-obsessed guy it seems to be that there should be a better option to handle these cases.

Answer 1

I noticed that as well and agree it a bit annoying, at the same time I don't think there is a perfect solution to it.

What you probably could to is something like

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