Documenting callback parameters using Google Closu

Question

How can you document names and descriptions of callback parameters using the Google Closure Compiler?

After reading this answer on documenting callbacks with JSDoc, I tried using @callback and @typedef and @name tags, but ran into issues with each one.

With @callback, Closure gives an "illegal use of unknown JSDoc tag" warning:

/**
 * @callback EndDrawCallback
 * @param {string} action - either "keep", "discard", or "cancel"
 * @param {boolean} saveChanges - whether to mark changes as saved
**/

With @typedef, it gives a "type annotation incompatible with other annotations":

/**
 * @typedef {function(string,boolean)}
 * @param {string} action ...
 * @param {boolean} saveChanges ...
**/
var EndDrawCallback;

Using @name, it gives a warning "Unknown type EndDrawCallback" when trying to use the callback name as a type:

/**
 * @name EndDrawCallback
 * @function
 * @param {string} action ...
 * @param {boolean} saveChanges ...
**/

The only alternatives I can see are

(a) to give up and write documentation after the callback param without using tags, or (b) to restructure the code to pass a single object into the callback, with named properties.

In this case at least, (b) is not an option. Is there a way to do this? If so, how?

Answer 1

Use the --extra_annotation_name flag to specify JSDoc tags that the compiler does not recognize. Since the compiler recognizes and uses @typedef, you would need to utilize either the @callback or @name annotations.