只是好奇什么是注释将传递给回调函数的参数的好方法。
假设我们有以下代码和不完整的注释
/**
* 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 参数调用回调的好方法是什么？
通常你只需要用说话的名字写一个函数的调用：
/*
* @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
*/
我不知道这方面的任何约定。我只会使用：
@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) 也是一个更好的主意。如果你必须选择一个，那就是。类型前的含义。
好吧，有很多方法可以在 javascript 中添加注释；这是我的建议/最佳实践。
using//比使用更好，/* */因为您可以使用后者取出包含其他注释的整个块。但是，如果要使用自动文档生成工具，则必须使用类似于 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
希望这会帮助你:)
/**
* 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);
}