What’s the proper way to document callbacks with jsdoc?

I’ve spent quite a while scouring the internet looking for the best way to properly document callbacks with jsdoc, but unfortunately, I haven’t found a great one yet.

Here’s my question:

I’m writing a Node.js library for developers. This library provides multiple classes, functions, and methods that developers will be working with.

In order to make my code clear and understandable, as well as to (hopefully) auto-generate some API documentation in the future, I’ve started using jsdoc in my code to self-document what’s happening.

Let’s say I define a function like the following:

function addStuff(x, y, callback) {
  callback(x+y);
});

Using jsdoc, I’m currently documenting this function as follows:

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {function} callback - A callback to run whose signature is (sum), where
  *  sum is an integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

I feel like the above solution is kinda hack-ish, since there’s no way for me to specify in absolute terms what the callback function should accept.

Ideally, I’d like to do something like:

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {callback} callback - A callback to run.
  * @param {int} callback.sum - An integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

The above seems like it’d allow me to more simply convey what my callback needs to accept. Does that make sense?

I guess my question is simple: what’s the best way to clearly document my callback functions with jsdoc?

Thank you for your time.

Answer

JSDoc 3 has a @callback tag for exactly this purpose. Here’s a usage example:

/**
 * Callback for adding two numbers.
 *
 * @callback addStuffCallback
 * @param {int} sum - An integer.
 */

/**
 * Add two numbers together, then pass the results to a callback function.
 *
 * @param {int} x - An integer.
 * @param {int} y - An integer.
 * @param {addStuffCallback} callback - A callback to run.
 */
function addStuff(x, y, callback) {
  callback(x+y);
}