Max Max - 3 months ago 8
Javascript Question

commenting callback functions

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

Usually you will just write a 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 {Bool}: whether a change has occured
 */