JavaScript annotated documentation (JSDoc): should @memberOf specify "prototype" as well?

Question

Example:

/**
 * @constructor
 * @Returns {AStar}
 */
function AStar() {


};

/**
 * @public
 *
 * Should this be:
 * @memberOf {AStar.prototype}
 * Or: 
 * @memberOf {AStar}
 *
 * @param {Number} startX
 * @param {Number} startY
 * @param {Number} destinationX
 * @param {Number} destinationY
 * @returns {Path}
 */
AStar.prototype.getPath = function(startX, startY, destinationX, destinationY) {
//(...)
};

For the function "getPath" added to AStar's prototype as in the code snipped above, should the annotated documentations on the "getPath" function specify:

@memberOf {AStar.prototype}

or

@memberOf {AStar}

?

I think according to this: http://usejsdoc.org/tags-memberof.html it should be AStar.prototype. In AStar you can have `this.position={};` and that would be a member of AStar. Another programmer would conclude that getPath would be shared by AStar instances but isn't a direct member. — HMR, Nov 16 '13 at 12:28

score 2 · Answer 1 · answered Apr 03 '14 at 11:41

The JavaScript code declares getPath as a method of AStar objects. If you do not provide the @memberOf tag, jsdoc is able to determine this by itself: the documentation lists getPath as a method of AStar objects. So you do not need to use either @memberOf options you cite in the question.

Moreover, in the specific case in your question jsdoc won't use your @memberof tag unless you use the form with the exclamation mark @memberof!. The form without the mark can be ignored by jsdoc if it thinks that it knows better than you what the method is a member of. The form with the exclamation mark forces jsdoc to not ignore it. So to have an effect on the documentation, you'd have to use @memberof!.

JavaScript annotated documentation (JSDoc): should @memberOf specify "prototype" as well?

1 Answers1