javascript - 评论回调函数

Question

只是好奇什么是注释将传递给回调函数的参数的好方法。

假设我们有以下代码和不完整注释

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

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

用 str 和 bool 作为参数调用回调有什么好方法？

Answer 1

通常你只会写一个函数的调用，并说出名字:

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

或者，如果参数需要解释，你可以使用多行描述:

/* 
 * @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
 */