2

Please consider following jsdoc-ed callback

/**
 * @callback create_stub
 * @param {Object} co_obj 
 * An object containing method to create the stub.
 * @param {string} method_name
 * A member function name of co_obj.
 * ...
 */

The above will work for JSDoc's documentation generator. Will be documented as typedef.

For Closure-Compiler however, it does not seem to work well. By "not work well" I mean:
Even if it works, compiler will not be able to perform type checks I think because -
the only solution for closure-compiler to use callback tag is just to remove the warning(See Documenting callback parameters using Google Closure Compiler).
Note: that solution did not work for me. I still get "Unknown type create_stub" warning.

For VS-Code: Intellisense will not work. See "https://github.com/Microsoft/TypeScript/issues/7515".
Now, with @typedef - everyone will be happy except that "I can not document parameters".

And, with @name (see Best way to document anonymous objects and functions with jsdoc) - generator will document callback as method rather than a typedef, closure-compiler seem to have no effects.

Finally, I would like to say that I am currently using my own workaround that uses both @name and @typedef to keep Generator, CC and VS-Code happy. Sample:

/**
 * @function
 * @name Klass.typedefs.create_stub
 * @param {Object} co_obj 
 * An object containing method to create the stub.
 * @param {string} method_name
 * A member function name of co_obj.
 * ...
 *//**
 * @private
 * @typedef {function(Object, string)} Klass.typedefs.create_stub
 */
 Klass.typedefs.create_stub; // this line is needed for Closure-Compiler compatibility

Thanks for your time.

SaMax
  • 169
  • 2
  • 10
  • How do you actually use the `create_stub` to annotate a callback? Or do you not do that, and your workaround is only for documentation purposes? – Carl G Nov 18 '19 at 16:57
  • 1
    @CarlG `@param {Klass.typedefs.create_stub} cb` – SaMax Nov 30 '19 at 20:39

0 Answers0