CODEWITHSUNDEEP
javascriptcoding-styledocumentationcomments
Max
Max

Reputation: 1459

commenting callback functions

Just curious what's a good way to comment what parameters will be passed to the callback function.

Suppose we have the following code and incomplete comments

/**
 * an utterly useless function
 *
 * @param {String} an useless string
 * @param {Boolean} an useless boolean
 * @param {Function} ???
 */

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

What's a good way to say callback will be called with str and bool are parameters?

Upvotes: 7

Views: 2451

Answers (4)

Linc
Linc

Reputation: 1299

/**
 * 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);
}

Upvotes: 1

Bergi
Bergi

Reputation: 664297

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

Upvotes: 5

Vikash Pandey
Vikash Pandey

Reputation: 5443

Well, there are many ways to add a comments in javascript; Here is my recommendation / best practices.

using // is better than /* */ because then you can use the latter to take out an entire block containing other comments. However, if you want to use an automatic documentation generation tool, you must use comments similar to javaDoc style.

This is an example that would work with YUI DOC (best one) 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 ;
    }

Other params Examples: - http://usejsdoc.org/tags-param.html

Hoping this will help you :)

Upvotes: 0

Charlie Rudenstål
Charlie Rudenstål

Reputation: 4338

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.

Upvotes: 2

Related Questions