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

Answer 2

我不知道有任何约定。我会用：

@param {Function} Called on success with the response (string) as the first param and the status code (int) as the second

我知道它虽然很冗长。

另一种选择就是这样做（类似于jQuery的做法，不是我所知道的代码，而是在他们的文档中）

@param {Function} onSuccess(response, statusCode)

以下是http://api.jquery.com/jQuery.ajax/的示例它当然是不同的，因为这是一个选项对象，文档与内联文档具有不同的结构。但是看看回调，你会看到相似之处。

为清晰起见，使用回调（response，statusCode）比回调（string，int）更好。如果你必须选择一个。类型前的含义。

Answer 3

嗯，有很多方法可以在javascript中添加评论;这是我的推荐/最佳做法。

使用//优于/* */，因为您可以使用后者取出包含其他注释的整个块。但是，如果要使用自动文档生成工具，则必须使用类似于javaDoc样式的注释。

这是一个适用于YUI DOC（最佳）http://developer.yahoo.com/yui/yuidoc/#start

的示例

/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} str - some string
* @param {Object} obj - some object
* @param {requestCallback} callback - The callback that handles the response.
* @return {bool} some bool
*/
    function SampleFunction (str, obj, callback) {
         var isTrue = callback(str, obj); // do some process and returns true/false.
         return isTrue ;
    }

其他参数示例： - http://usejsdoc.org/tags-param.html

希望这会对您有所帮助：）

Answer 4

/**
 * an utterly useless function
 *
 * @param {String} an useless string
 * @param {Boolean} an useless boolean
 * @param {(param1:Number, param2:String ...)=>{}} callback
 */

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

评论回调函数

4 个答案: