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

rdegges :

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.

Jeff Williams :

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

Collected from the Internet

Please contact [email protected] to delete if infringement.

edited at
0

Comments

0 comments
Login to comment

Related

What's the best way to document an array of arrays of arrays using JSDoc?

What is the proper way to document a CMake module?

Is this the proper way to use callbacks in Swift?

What's the proper way to setup an Android PreferenceFragment?

What's the proper way to share the interface?

What's the proper way to check if a constant is defined?

What's the proper way of passing a ref to a prop?

What's the proper way to propagate .catch in promise?

What's the proper way to recurse in LLVM assembly?

What's the proper way to link to a route with parameters?

What's the proper way of Naming a class?

What's the proper way to reraise a custom exception?

What's the proper way to write a haskell function

What's the proper way of changing the color of SetDlgItemText?

What's the proper way to use Coroutines in Activity?

What's the proper way to make the AppBar fixed?

What is the proper way of saving data to an embedded document using Mongoengine and Pyramid?

What is the proper way to check if a document in mongodb with find().limit()?

What is the proper way to format this txt document with csv writer and pandas?

What is the correct way to specify an object's class with the JSDoc 3 syntax?

What is the proper/canonical formatting of long JSDoc lines?

What's a clean way to test that no callbacks are registered on an ActiveRecord object?

What's the proper way of using Swift's defer

Best way to document anonymous objects and functions with jsdoc

How to document nested properties in JSDOC in a readable way?

What's the standard way to document a namedtuple?

MVVM - What's the proper way to communicate between views in WPF

What's the proper way to parse a very large JSON file in Ruby?

In BeautifulSoup, what's the proper way to use a strainer with lxml parsing?