1

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?

Community
  • 1
  • 1
Chris Middleton
  • 5,654
  • 5
  • 31
  • 68
  • Are you just wanting the jsdoc for documentation generation? Or do you want to use them for closure compiler type checking? – Chad Killingsworth Nov 24 '15 at 17:12
  • Type checking would be a bonus, but mostly I just want to get the documentation in there with as little repetition as possible. The main source of repetition here is doing `function(string,boolean)` and then `@param {string} ...`. Having it in two different comment blocks means it might easily diverge, so it would be great to define the callback type once and then just reference it. – Chris Middleton Nov 24 '15 at 17:15

1 Answers1

0

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.

Chad Killingsworth
  • 14,360
  • 2
  • 34
  • 57