What is the convention for documenting arguments passed to a javascript callback?

Question

When using the javadoc style documentation style, is there a convention for documenting the arguments passed to the callback function?

/** * @param cb {Function} A callback that will be passed a name (String) and a Number / 

Answer 1

This has more to do with events than with callbacks, but I wanted to post it as it can help you in related cases. If you also fire up an event when a callback is called, you can use this approach to document the event, and then in your callback documentation, note that it receives the same parameters as the event, and an event link using @link.

I use something like what you see below to document events in F.js. It is not associated with any specific code, and I dumped it at the bottom of the script that defines F.Component:

 /** * Triggered when this component is shown * * @name F.Component#component:shown * @event * * @param {Object} evt Event object * @param {String} evt.name This component name * @param {F.Component} evt.component This component */ 

The above JSDoc statement leads to documentation that looks like this: when built using jsdoc-toolkit. Basically, you get a nice section "Event Details" that describes when the event is triggered and what parameters are passed to the callback. This also works with JSDoc3 and leads to the Events section with the same information.

Note that the documentation describing the @event tag does not exactly describe it that way, but it does give the desired release. In JSDoc3, @event and @firees tags do not yet have documentation, but @event gives the result I was looking for.