gajus / eslint-plugin-jsdoc

JSDoc specific linting rules for ESLint.
Other
1.09k stars 157 forks source link

`informative-docs` - Allow for excluded tags #1153

Closed tetarchus closed 12 months ago

tetarchus commented 1 year ago

Motivation

In setting an options object for a library, I would like to be able to record the default value in the comment for each option, to assist with documentation, including in-line hover docs in VSCode.

Currently informative-docs reports on all tags.

Current behavior

Using a 'simple' value for the @default tag causes this rule to report an issue:

/**
 * My option.
 * @default {} <-- Reports 'This tag description only repeats the name it describes.'
 */

This seems to be the case for {}, [], '' values that may wish to be defined as default values to indicate that the default is empty - especially in cases where the option accepts multiple different types being assigned to it.

Desired behavior

Introducing the option to exclude tags would allow ignoring these errors on parts of the documentation where we have a different preference - i.e. assigning a 'simple' default value - while also preserving the current behavior for other tags, and for those who want it for all tags (by default it would still apply to all tags).

Alternatives considered

Currently the only alternative is to disable the rule (either entirely, or for the file) which then removes this check on the description part of the doc comment.

github-actions[bot] commented 12 months ago

:tada: This issue has been resolved in version 46.6.0 :tada:

The release is available on:

Your semantic-release bot :package::rocket: