Easy way to document callbacks

[hazeledmands]

This is a pretty common trope in JS code:

someAsyncFunction('parameter1', function parameter2(err, result) {
    if(err) {
          console.err(err.toString());
              return;
                }
                  console.log(result);
});

or as in underscore or lazy.js:

lazy([1,2,3]).map(function(index, value) {
    return index + value;
}).toArray();

Right now, when documenting these API's, we have to resort to something like:

/**
* Does some async thing!
* @argument {string} foo This is very unimportant.
* @argument {function} callback When we've finished our calculation, we call this function and provide it two arguments -- the first is an error, which will be `null` if everything works out okay, and the second is an instance of `HolyGrail` which will make all your dreams come true.  
*/
someAsyncFunction: function(foo, callback) {
     // ...
}

This seems less than ideal. JSDoc provides the @callback tag, which might be the optimal solution here. What do you think?

[dtao]

Yeah, I think I agree here. I was also planning on adding support for the @typedef tag soon as well; I think @callback support could be added around the same time.