Question

Just curious what’s a good way to comment what parameters will be passed to the callback function.

Suppose we have the following code and incomplete comments

/**
 * an utterly useless function
 *
 * @param {String} an useless string
 * @param {Boolean} an useless boolean
 * @param {Function} ???
 */

function Useless (str, bool, callback) {
  callback(str, bool);
}

What’s a good way to say callback will be called with str and bool are parameters?

Answer 1

Usually you will just write an invocation of the function with speaking names:

/* 
 * @param {String} input: the text
 * @param {Function} callback(output, hasChanged): called after calculation
 */

Or, if the parameters need explanation, you can use a multiline description:

/* 
 * @param {String} input: the text
 * @param {Function} callback(result, change)
 *         the function that is called after calculation
 *         result {String}: the output of the computation
 *         change {Boolean}: whether a change has occurred
 */