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

javascript, jsdoc

Solution

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).

Problem

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.

Original source