RFC: "@suppress" tag for suppressing individual diagnostics

[microsoft]

RFC: "@suppress" tag for suppressing individual diagnostics

[aciccarello]

@pgonzal Sure. My gut reaction is that if you frequently need to suppress parts of tsdoc, you are getting more into a docs linter. While that may be helpful when generating documentation, I don't know that it should be part of tsdoc core, especially early on. My impression is that linter rules change frequently and maintaining them in the core library could complicate things.

Coming from typedoc's loose parsing of doc comments, I don't see myself looking for this feature to be included.

[octogonz]

@aciccarello could you provide a little more detail? :-P Does the design seem misguided? Or are you just saying that you wouldn't personally need this feature?

Is your concern mainly with the @suppress tag, or do you also dislike the idea of labeling each error with a name such as ae-undocumented-link-target? I also considered the TypeScript compiler's approach, where diagnostics have numbers (e.g. TS1003). However that seemed less readable.

[octogonz]

@aciccarello I've come around to the same viewpoint. The most common use case for suppressions is to bulk-ignore all legacy violations, so that we can start applying the stricter rules for new changes going forward. In this situation, tracking suppressions in source code comments is clumsy and clutters the code. Such suppressions really need to go in a file (e.g. suppressions.json) that can be easily generated by a tool.

I'm going to close this RFC.