Max Max - 1 month ago 4x
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?


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