commenting callback functions
Usually you will just write an invocation of the function with speaking names:
/*
* @param {String} input: the text
* @param {Function} callback(output, hasChanged): called after calculation
*/
Or, if the parameters need explanation, you can use a multiline description:
/*
* @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
*/
I don't know about any conventions for this. I would just use:
@param {Function} Called on success with the response (string) as the first param and the status code (int) as the second
I am aware it's quite verbose though.
Another option would be doing it like this (similar to how jQuery does it, not in code that I am aware of, but in their documentation)
@param {Function} onSuccess(response, statusCode)
Here's an example http://api.jquery.com/jQuery.ajax/ It's different of course since this is an options object and the documentation has a different structure than inline documentation. But look at the callbacks and you will see the similarity.
It's also a much better idea to use callback(response, statusCode) than callback(string, int) for clarity. If you have to choose one that is. Meaning before type.