Is There Any Way to Avoid Using the JSDoc "@method" Annotation

Question

I'm not a big fan of generated documentation personally (I'm more of a "read the source Luke" kinda guy), but I can see how such documentation might be useful to others. Now, normally their generating of documentation wouldn't impact me, except for one thing: @method.

Most JSDoc annotations (eg. @param) are still perfectly useful to someone reading the source, but @method is 100% redundant:

/*
 * @param num number to add five to
 * @method addFive
 */
function addFive(num) { ...

So, I'd really like to avoid having hundreds of @method lines cluttering up our code. However, my co-worker believes that @method is necessary for the JSDoc generators (he's using the YUI one) to be able to generate the method lists of classes.

So, my question (to the JSDoc experts out there) is: is there any way to generate useful documentation (ie. with the methods of a class listed) without @method? Or if @method is truly required, is there any JSDoc generator that can infer the method name from the function name, so that I can get away with @method instead of @method addFive?

P.S. If there's a "you're doing it wrong"-type answer that doesn't directly answer the question but suggests a way of avoiding the problem entirely, I'd love to hear it; I'm certainly no JSDoc expert.

Answer 1

Your co-worker is not strictly correct.

The @method is a JSDoc3 extension that is a synonym for @function, which is defined here.

As those docs outline, you only need to use @function to force JSDoc to recognise a variable as being a function. An example of this would be:

/**
 * @function
 */
var func = functionGenerator.generate();

From an object perspective, you'd want to do the same whenever you assign a Function object to an object member in a non-obvious way (by 'non-obvious', I mean in terms of static analysis, i.e. if you're not using a function expression).

So, something like

var ageGetter = function() {
    console.log("A lady never tells");
}

var Person = {

  name: "Gertrude", 

  getAge: ageGetter

  getName: function() {
    return this.name;
  }
}

Would require explicit use of @method or @function for getAge, but not for getName.

Final point: you do not need to explicitly include the @method name unless that, too, is impossible to infer (at which point, you're probably doing some pretty funky instantiation, so probably haven't been able to rely on auto doc-generation much anyway).

Answer 2

I might be wrong here but because of the multitude of ways to define things in JavaScript you kind of need @method for certain definitions.

// JSDoc will recognize this as an object member
var obj = {
    mymethod: function() {}
};

// There is no way for JSDoc to tell where my method is going to end up
var mymethod = function() {};
obj.mymethod = mymethod;