Validate annotation tag names

[pigulla]

It would be nice if the plugin could also validate annotation names, e.g.:

/**
 * @pubblic
 */

would fail because no such tag exists (typo).

Ideally, there would be various ways to configure this:

"jsDoc": {
    "checkAnnotations": "jsdoc"  // whitelists JSDoc tags
    // or
    "checkAnnotations": "jsduck"  // whitelists JSDuck tags
    // or
    "checkAnnotations": "closurecompiler"  // whitelist Closure Compiler tags
}

Might be a good idea to add version support from the get-go, so use jsdoc3, jsduck4, jsduck5 etc.

[qfox]

There are two solutions from my pov:

• make some kind of dictionaries with these sets (and their formats)
• make a set of flexible rules to configure and make presets with right values for them

I think better to have presets. But if you've make some basic realization e.g. jsduck set I'll do the rest. So PR is welcome. Thanks for ideas!

upd: Btw, we can parse JSDuck set from their wiki. And I think there're same possible solutions for JSDoc3 and Google Closure tag sets. Tag is what you calling "Annotation Name". Anywhere in code you'll see "tag".

[pigulla]

I've created a PR with a first draft for presets for JSDuck 5, JSDoc 3 and the Closure Compiler.

As far as validation is concerned, that's about as far as I would want to go. Although I'm not sure where we should define which tags expect a type expression that needs to be validated. For instance, the syntax for @this is "@this" <type-expression> whereas it is "@param" <type-expression> <description> for the @param tag.
Maybe the most straight forward solution is to simply assume that everything that directly follows a tag and that looks like a type expression (i.e., is in curly braces) actually is meant to be one.

Also, it's probably a good idea to extend the configuration like so:

"jsDoc": {
    "checkAnnotations": "jsduck"  // whitelists JSDuck tags
    // equivalent to
    "checkAnnotations": {
        "preset": "jsduck"
    }
    // which can be extended to
    "checkAnnotations": {
        "preset": "jsduck",
        "extra": {
            "mycustomtag": false
        }
    }
}

because we need to take into account that tools like JSDuck allows the definition of custom tags.

[qfox]

Wow, nice work. Atm all tags parsing with rule @tag( {type})?( name)?( description)? I thinking about strict typing (more than true/false) for values in presets. As I can see there are boolean tags (flags) like @abstract, @chainable, etc. There are also valuable tags like @link, @see, @uses?. Typed tags like @type, @return[s], @param. And others. I propose to use true value for default behaviour (just tag filtering/checking), "boolean" for no data after tags, "typed" for @type. Probably we can also use regexes for custom tags.

Another idea is to use patterns for tags. For example:

{
  "type": "<type> <description>",
  "var": "<type> <description>",
  "param": "<type> <name> <description>",
  "returns": "<type> <description>"
}

What you think?

[qfox]

@pigulla I've made some basic functionality for this. Can you take a look at PR?