Parse error, illegal use of unknown JSDoc tag "callback"

[i0n-]

I want to use the callback annotation to document 'callback' parameters.

The @callback tag is documented here https://jsdoc.app/tags-callback.html
And is not here yet: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler

[4r7d3c0]

How are you even getting this error?

/** @const */
var _protypes = {}

/**
 * The callback.
 * @param {string} name The arg
 * @callback
 */
_protypes.subtypeCallback = function(name) {}

/**
 * Copy properties from prototypes into the class's prototype.
 * The target class's prototype is modified itself.
 * @param {typeof _protypes.subtypeCallback} callback The function to call upon success.
 */
_protypes.subtype = function(callback) {
  callback('world')
}

let a
_protypes.subtype((name) => { a = `hello ${name}` })
console.log(a)

Version: v20200830
Built on: 2020-09-01 01:47

Compiled down to:

'use strict';console.log("hello world");

JSDoc doc give examples in some weird format where callback is just defined as global in comments. That wouldn't work in Closure. You need some kind of global underneath the comment. Still I have no clue how you get the parsing error from the @callback tag in comments. Probably because your comment block is merging with something beneath or above with which is incompatible with @callback.

Although jsdoc comments are used in Closure, I wouldn't say that they're 100% compatible. But you might have some luck by just adding a blank function signature under your comment block. Maybe. But then there's typeof which is actually the correct usage according to the type system, I suppose. It's not required for JSDoc or for VSCode, but if you don't put typeof for the callback type there'll be an error:

t/callback.js:6:11: WARNING - [JSC_UNRECOGNIZED_TYPE_ERROR] Bad type annotation. Unknown type _protypes.subtypeCallback

which goes away once you put typeof.

[nreid260]

@callback has no meaning to Closure Compiler and is rejected as likely being a typo.

The canonical list of supported annotations is here. This of course depends if you're using a build with this resource file.

[4r7d3c0]

@nreid260 could you please clarify why is not rejected in my code then? If you couldn't put any of your own JSDoc tags in JS, that'd be pretty limiting, I don't think Closure rejects JSDoc by tags, it must be because of something underneath the comment. Can you please provide an example.

[nreid260]

@i0n- Are you using the same compiler version as @4r7d3c0 ?

The list of approved annotations is just a resource file. If that were swapped out, the parsing error would change. I'm not sure that linked file is used outside of Google since JSDoc can be quite diverse.

That said, the annotations linked in the file are the only ones the compiler might interpret as having semantic meaning, even if others make it though parsing.

[nreid260]

The --extra_annotation_name flag might be helpful here, at least short term.