Allow rules with contexts to also check for presence of particular tag

[brettz9]

I'd like to see rules with contexts be allowed to specify a special type of context which allows checking particular contexts, including the global context (i.e., a jsdoc block not associated with code) while insisting that a particular tag be present, e.g., @external, @module, @typedef, @function (including as a virtual function with @interface) and @callback.

The specific use case of global contexts wouldn't be useful for some rules with contexts options, e.g., require-jsdoc or probably require-example (which assume a code context), but it would be helpful for some rules like require-description and match-description which allow contexts, but do not allow checking that descriptions accompany those global tags specifically (see #407 for one such case).

If we allow generic contexts like "function" (as I think we should) as in #384, we could also consider including these tag-associated contexts (e.g., a "function" could include interface based ones).

And this could be useful for non-global contexts, e.g., ensuring an @author is present on classes, or whatever conditions a project might want. Note: I've filed eslint/eslint#12975 which would enhance the usability of this proposed rule (i.e., to allow selective enabling/disabling within a file so it might only be required for a particular object or block).

(This issue to whitelist rules from certain contexts only when specific tags are present is a converse of #466 which seeks to blacklist rules from certain contexts only when certain tags are present.)

Particularly this case of checking for tags, but even for rules just using regular contexts, it would also be helpful to allow defining a custom message, e.g., "Please add a @cli-arg tag here so we know which arguments are passed into this file" (e.g., when overrides is targeting all files within /bin).

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[brettz9]

This might not be necessary if we get AST for jsdoc (see discussion from #483 (comment) )

[brettz9]

See also syavorsky/comment-parser#117

[brettz9]

I'm thinking now that we should still implement this rule despite what bringing comments to AST could bring.

While it would be convenient to get this ability of the box with our esquery statements as estree/estree#41 might make possible, I think there is a need for this today. (We might in fact be able to allow esquery expressions now against an EStree AST-friendly form of our comment-parser and jsdoctypeparser AST, perhaps with a separate option for querying the comments if tacking in on proves too involved.)

[brettz9]

Note that with this feature implemented, it would be much easier to move the apparently now abandoned https://github.com/esmbly/esmbly/blob/master/docs/using-the-jsdoc-transformer.md project forward such that linting could ensure a plain JS+JSDoc project can be compiled into TypeScript which can in turn be compiled by AssemblyScript into WebAssembly for native performance.

But without linting to inform JS+JSDoc users that their types are too ambiguous for native purposes, it is far less attractive as a development process.

[brettz9]

Closing as comment in contexts can meet the need.