评论回调函数

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