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

Question

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.

Answer 1

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);
}