评论回调函数答案

【问题标题】：commenting callback functions评论回调函数
【发布时间】：2012-08-01 00:39:26
【问题描述】：

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

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

/**
 * 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 参数调用回调的好方法是什么？

【问题讨论】：

回调函数通过str和bool?我不确定是什么问题。
问题是如何以干净的方式评论它
那么说回调将传递其他两个参数有什么问题？
请参阅 Charlie Rudenstål 的回复。这就是我的做法，也是我不开心的原因。我觉得它很冗长，希望有人有我可以使用的“{Type} 描述”样式模式。
第一个例子是不必要的冗长，我怀疑是故意的。我只想说callback(str, bool) 并添加任何必要的上下文信息。其他任何内容都应该放在主文档中，而不是参数文档中。

标签： javascript coding-style documentation comments

【解决方案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
 */

【讨论】：

【解决方案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/ 它当然是不同的，因为这是一个选项对象，并且文档具有与内联文档不同的结构。但是看看回调，你会看到相似之处。

为了清楚起见，使用 callback(response, statusCode) 比使用 callback(string, int) 更好。如果你必须选择一个，那就是。类型前的含义。

【讨论】：

是的，这正是我目前的做法，也是我不开心的原因
用一个从 jQuery 文档中获得灵感的示例对其进行了更新

【解决方案3】：

嗯，有很多方法可以在 javascript 中添加 cmets；这是我的建议/最佳做法。

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

这是一个适用于 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

希望对您有所帮助:)

【讨论】：

【解决方案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);
}

【讨论】：