Avoid erring with "event:" within @param and @returns tags and any other allowed contexts

[brettz9]

What version are you using?

That on https://eslint.org/doctrine/demo/

What JSDoc comment were you trying to parse?

I used "event:" as part of a string comprising an event name reference within @param:

/**
 * Report the throwing of a snowball.
 * @method
 * @param {module:hurler~event:snowball} e - A snowball event.
 * @listens module:hurler~event:snowball
 * @returns {undefined}
*/

What Doctrine options were you using (sloppy, unwrap, etc.)?

No options except toggling the demo's "recoverable" option with different results apparently because it normally errs (whereas it shouldn't).

What happened? Include output if possible.

It gives:

{
    "description": "/**\nReport the throwing of a snowball.",
    "tags": [
        {
            "title": "method",
            "description": null,
            "name": null
        }
    ]
}

...though when "recoverable" is checked, it gives:

{
    "description": "/**\nReport the throwing of a snowball.",
    "tags": [
        {
            "title": "method",
            "description": null,
            "name": null
        },
        {
            "title": "param",
            "description": "A snowball event.",
            "type": null,
            "errors": [
                "not reach to EOF"
            ],
            "name": "e"
        },
        {
            "title": "listens",
            "description": "module:hurler~event:snowball"
        },
        {
            "title": "returns",
            "description": "/",
            "type": {
                "type": "UndefinedLiteral"
            }
        }
    ]
}

I get similar problems if adding the event to @returns instead of @param.

What did you expect to happen?

I'd expect the output to look more like the "recoverable" option (or at least how it should be if "event:" weren't a problem inside of @param).

The JSDocs (for @listens) states:

The following example shows how to document an event named module:hurler~event:snowball, as well as a method named module:playground/monitor.reportThrowage that listens for the event...

So "event:" should be permitted within references to events (including @param) without complaint, at least at preceding a property name at the beginning of namepaths (#, ., or ~ for JSDoc 3, and apparently -, if supporting JSDoc 2), so, e.g., MyClass#event:foo or MyClass~event:foo.

The code above was even taken from http://usejsdoc.org/tags-listens.html (with @returns added to avoid the error about it missing @returns). This code uses event: within a @param, and if this is removed, doctrine shows no difference with "recoverable" checked or unchecked (and it includes more info such as the listens and returns results), i.e., apparently ceasing to err (the @listens use is not problematic).

Even if one could work around this by avoiding "event:" within event names, it is not only explicitly permitted by JSDoc but is helpfully descriptive in distinguishing such events from other object references.

Moreover per http://usejsdoc.org/tags-event.html , it appears it may be even required in some locations (and is explicitly permitted in the signature):

Syntax

@event <className>#[event:]<eventName>
...
JSDoc automatically prepends the namespace event: to each event's name. In general, you must include this namespace when you link to the event in another doclet. (The @fires tag is a notable exception; it allows you to omit the namespace.)

[kaicataldo]

Thanks for this issue. We have decided to officially end-of-life JSDoc support in ESLint. As a result, this repository and project will no longer be maintained.

Thanks for understanding and we apologize for any inconvenience.