eslint-plugin-tsdoc: allow policies to be ignored in tsdoc/syntax rule

Now that less-strict parsing for @param tags is merged (https://github.com/microsoft/tsdoc/issues/128), I’d love to be able to loosen the requirements of the tsdoc/syntax rule to allow for certain deviations from the expected syntax.

Primarily, VSCode’s built-in JSDoc support automatically adds a doc comment where each @param tag is followed immediately by a description, without the expected hyphen. With the following .eslintrc configuration:

{
  rules: {
    'tsdoc/syntax': 'warn'
  }
}

This snippet is valid:

/**
 * Description
 * @param a - first number
 * @param b - second number
 */
const add = (a: number, b: number) => a + b;

While this snippet:

/**
 * Description
 * @param a first number
 * @param b second number
 */
const add = (a: number, b: number) => a + b;

Warns with the following:

tsdoc-param-tag-missing-hyphen: The @param block should be followed by a parameter name and then a hyphen eslint(tsdoc/syntax)

I’d love to be able to ignore this particular syntax deviation with something like:

{
  rules: {
    'tsdoc/syntax': ['warn', ignore: ['tsdoc-param-tag-missing-hyphen'] ]
  }
}

[rob4226]

Yes, please an "ignoreMessageIds" is very much needed. Unless I am missing something it seems the eslint-plugin-tsdoc is all or nothing. Is there any way to stop reporting on some message ids at the moment?

[octogonz]

This is a good idea. However I think we might want to approach it via the tsdoc.json config file rather than via ESLint’s configuration. The reason is that you are not really suppressing a warning, but rather defining the kind of TSDoc parsing that you want for your source files. Putting the suppression in tsdoc.json will prevent other tools from reporting the same errors when they invoke the parser.

Long term, we intend to provide a “lax mode” as well as other compatibility settings for the TSDoc parser. But in the short term, this kind of problem can be solved pretty well by simply filtering out specific error IDs as you suggest. (The reason that’s not a perfect solution is that the syntax highlighting may sometimes color the bad characters in red even though the error message is hidden.)

eslint-plugin-tsdoc already supports tsdoc.json, so we would simply need to improve tsdoc.schema.json to support something like this:

your-project/tsdoc.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "ignoreMessageIds": [
    "tsdoc-config-file-not-found"
  ]
}

…and then pass that setting through to the parser. It’s mostly plumbing work, since in the end all we’re doing is adding a filter to ParserMessageLog.addMessage().