Callback support in @param

[GoogleCodeExporter]

Something, like:

/**
 * @param {Function} callback(HTMLElement element, String url)
 */
function foo(callback)
{
    callback(document.createElement('div'), 'example.com');
}

Alternative:
/**
 * @param {Function} callback(element, url)
 * @param {HTMLElement} callback().element Some element
 * @param {String} callback().url Some url
 */
function foo(callback)
{
}

What do you think?

Original issue reported on code.google.com by m...@list.ru on 24 Mar 2011 at 2:34

[GoogleCodeExporter]

The alternative option is better, since callback parameters needs to be 
documented with description as well.
For example, see the Google Chrome Extensions API documentation, which is 
entirely async and full of callback methods (ex. page: 
http://code.google.com/chrome/extensions/tabs.html)

Do you know by any chance if they (Google) are using JSDoc toolkit?

Is there a chance to have support in callback methods before version 3?

Original comment by lira...@gmail.com on 26 Jun 2011 at 2:23

[GoogleCodeExporter]

+1 for specifying a callback syntax... callbacks are so prevalent with 
asynchronous programming, knowing what callback passthrough in JSDoc would be 
great.

Original comment by qv.perso...@gmail.com on 12 Jan 2012 at 3:20

[GoogleCodeExporter]

The syntax in #1 is misleading as it looks like element and url where 
attributes of the return value of the callback.

A suggestion in accordance with existing jsdoc tags:

/**
 * @param {Function} callback foo(element, url) called when something happens
 * @callbackparam {HTMLElement} element Some element
 * @callbackparam {String} url Some url
 * @param {Number} otherValue the parameter list continues
 */
function foo(callback, otherValue)
{
  // ....
  callback(document.createElement('div'), 'example.com');
}

Original comment by sai...@38.de on 24 Oct 2012 at 8:34

[GoogleCodeExporter]

See https://github.com/jsdoc3/jsdoc/issues/260 for a related discussion.

Original comment by cow...@bbs.darktech.org on 6 Dec 2012 at 9:33