Ability to document callback arguments

[cowwoc]

We need a way to document callback argument. For example, given:

var MyFunction = function(onSuccess, onFailure) { ... }

I need to document the arguments I will be passing into onSuccess and what return values are acceptable. There are workarounds for documenting the callback parameters, but they result in documentation that is hard to read. There is no known workaround for documenting the callback return values.

[hegemonic]

I completely agree that this is needed. I'll confer with @micmath; there have been many different syntax proposals for this in the past, and I'm not familiar with most of them.

[cowwoc]

My 2 cents...

This is a recursive problem. The callback could have its own callback. As I don't think we should document callbacks in-line. One approach would be to uniquely name each callback and @link to its documentation. We should be able to document the callback parameter briefly and link the user to a more detailed explanation. For example: "this callback is invoked on success. See {@link MyCallback} for more information".

[gaurav21r]

+1

[qubyte]

+1 I could really use this right now! :)

[cowwoc]

See http://code.google.com/p/jsdoc-toolkit/issues/detail?id=319 for a related discussion.

[hegemonic]

Via email, @micmath pointed out that there's already a way to do this by documenting the callback as an inner function. No new tags required! Here's an example:

/**
 * Classy class.
 * @class
 */
function TestClass() {}

/**
 * Called after doing asynchronous stuff.
 * @name TestClass~TestCb
 * @function
 * @param {String} err - Information about the error.
 * @param {Number} int - An integer of joy.
 * @return undefined
 */

/**
 * Do asynchronous stuff.
 * @param {string} name - A name.
 * @param {TestClass~TestCb} callback - The callback function.
 * @return undefined
 */
TestClass.prototype.doAsyncStuff = function(name, callback) {
    // ...
};

I believe @micmath is planning to say more about this on the mailing list.

Leaving this ticket open for now as a reminder that we really need to document this approach.

[micmath]

That plan is underway. I'll put something together this weekend.

[micmath]

Simplest possible example:

/**
 * @class
 */
function MyClass() {}


/**
 * Do asynchronous stuff.
 * @param {MyClass~onSuccess} onSuccess - Called if doing asynchronous stuff succeeds.
 */
MyClass.prototype.doAsyncStuff = function(onSuccess) {
    // ...
};

/**
 * @function MyClass~onSuccess
 * @param {String} result - The result of the asynchronous process.
 * @param {Number} int - A result code.
 * @return undefined
 */

If you needed to document things about callback parameters immediately you can follow that pattern. It might be possible to sugar this sort of thing up in a slightly sweeter syntax by patching JSDoc.

[neekey]

@micmath Thanks for providing such kind of way to document callback params, just wonder if you are still working on that slightly sweeter syntax.

[micmath]

I'm not working on this, it's not a feature I would use, but as you you know JSDoc is and always has been open source and if there is any user who want this enough to submit a patch, then I'm sure it will be accepted.

There is a little more to it though, as I think I might have mentioned in a/this thread previously, there is prior art in this area with Google's Closure Compiler. So they would expect a syntax like this:

/**
    A function that takes a callback.
    @param {function(string, boolean):object} callback Takes a string and a boolean, returns an object.
 */
function doStuff(callback) {
}

If JSDoc were to add more support for callbacks, it should probably follow that standard (which, I should point out, was published after JSDoc, and without any discussion with the JSDoc community but is based on a proposal for type annotations from ECMAScript 4th Edition). And actually, if we want to open that door, there are a whole slew of similarly more complex type specification like that that JSDoc could support, and we might as well try to support the lot with a full-on type specification parser, if such a thing exists. Presumably JSDoc would then support arbitrarily nested callback params like so...

/**
    A function that takes a callback.
    @param {function(string, function(number):boolean):function(function(string))} callback A callback that takes a string and a callback that takes a number and returns a boolean, returns a callback that takes a callback that takes a string.
 */
function doStuff(callback) {
}

If support for that specific syntax is wanted, I'd suggest a new issue be raised with that as the feature request, and maybe someone will pick it up.

Michael Mathews
micmath@gmail.com

ref
https://developers.google.com/closure/compiler/docs/js-for-compiler
http://wiki.ecmascript.org/lib/exe/fetch.php?id=spec%3Aspec&cache=cache&media=spec:core-language-d2.html

[cowwoc]

Michael,

I highly dislike this syntax. It involves cramming the description of an entire callback and its parameters into a long line. What happens if a callback takes another callback as an argument? What then? This approach does not scale.

[hegemonic]

I have to say that the callback syntax that's already supported (as described above in @micmath's MyClass~onSuccess example) seems pretty darned good to me. It's far more straightforward than the many other suggestions I've seen on the mailing list in the past. It also scales well for nested callbacks.

I agree with @cowwoc that the Closure Compiler syntax does not lend itself to clear documentation. Fortunately, we already support something much better!

Again, I'm just keeping this issue open as a reminder that we need to document the existing syntax and share it with the mailing list.

[micmath]

@cowwoc I highly agree with you. It's not a nice syntax. In fact it's awful.

[neekey]

@micmath It seems like there is still some problem with the way you provided:

The code below will only generate a simple title for Next without description of params.

/**
 * An simple tool set.
 * @type {Object}
 */
var Tool = {};

/**
 * Do something Async...
 * @param {Next} next
 */
Tool.getURL = function( next ){

};

/**
 * Called if Fetching URL is done.
 * @function Next
 * @param {String} url
 * @returns undefined
 */

And if I add ~ like below:

/**
 * Called if Fetching URL is done.
 * @function Tool~Next
 * @param {String} url
 * @returns undefined
 */

Than the Next will become the inner method for Tool, but still, the link from the description of Tool.getURL will be an anchor like Tool#Next which is incorrect.

[neekey]

@micmath I found an issue from YUIDoc, with tag @callback to indicate a method as callback, yui/yuidoc#33