☂️ eslint-plugin-jsdoc

[camc314]

[!WARNING] This comment is maintained by CI. Do not edit this comment directly. To update comment template, see https://github.com/oxc-project/oxc/tree/main/tasks/lint_rules

This is tracking issue for eslint-plugin-jsdoc.

There are 57(+ 0 deprecated) rules.

• 12/30 recommended rules are remaining as TODO
• 27/27 not recommended rules are remaining as TODO

To get started, run the following command:

just new-jsdoc-rule <RULE_NAME>

Then register the rule in crates/oxc_linter/src/rules.rs and also declare_all_lint_rules at the bottom.

Recommended rules

✨: 18, 🚫: 0 / total: 30

| Status | Name | Docs | | :----: | :--- | :--- | | ✨ | jsdoc/check-access | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-access.md#repos-sticky-header | | | jsdoc/check-alignment | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-alignment.md#repos-sticky-header | | | jsdoc/check-param-names | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-param-names.md#repos-sticky-header | | ✨ | jsdoc/check-property-names | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-property-names.md#repos-sticky-header | | ✨ | jsdoc/check-tag-names | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md#repos-sticky-header | | | jsdoc/check-types | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-types.md#repos-sticky-header | | | jsdoc/check-values | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-values.md#repos-sticky-header | | ✨ | jsdoc/empty-tags | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/empty-tags.md#repos-sticky-header | | ✨ | jsdoc/implements-on-classes | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.md#repos-sticky-header | | | jsdoc/multiline-blocks | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/multiline-blocks.md#repos-sticky-header | | ✨ | jsdoc/no-defaults | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-defaults.md#repos-sticky-header | | | jsdoc/no-multi-asterisks | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-multi-asterisks.md#repos-sticky-header | | | jsdoc/no-undefined-types | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md#repos-sticky-header | | | jsdoc/require-jsdoc | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-jsdoc.md#repos-sticky-header | | ✨ | jsdoc/require-param | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header | | ✨ | jsdoc/require-param-description | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-description.md#repos-sticky-header | | ✨ | jsdoc/require-param-name | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-name.md#repos-sticky-header | | ✨ | jsdoc/require-param-type | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-type.md#repos-sticky-header | | ✨ | jsdoc/require-property | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property.md#repos-sticky-header | | ✨ | jsdoc/require-property-description | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-description.md#repos-sticky-header | | ✨ | jsdoc/require-property-name | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-name.md#repos-sticky-header | | ✨ | jsdoc/require-property-type | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-type.md#repos-sticky-header | | ✨ | jsdoc/require-returns | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header | | | jsdoc/require-returns-check | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header | | ✨ | jsdoc/require-returns-description | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header | | ✨ | jsdoc/require-returns-type | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header | | ✨ | jsdoc/require-yields | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md#repos-sticky-header | | | jsdoc/require-yields-check | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-check.md#repos-sticky-header | | | jsdoc/tag-lines | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/tag-lines.md#repos-sticky-header | | | jsdoc/valid-types | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/valid-types.md#repos-sticky-header | ✨ = Implemented, 🚫 = No need to implement

Not recommended rules

✨: 0, 🚫: 0 / total: 27

| Status | Name | Docs | | :----: | :--- | :--- | | | jsdoc/check-examples | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-examples.md#repos-sticky-header | | | jsdoc/check-indentation | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-indentation.md#repos-sticky-header | | | jsdoc/check-line-alignment | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-line-alignment.md#repos-sticky-header | | | jsdoc/check-syntax | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-syntax.md#repos-sticky-header | | | jsdoc/check-template-names | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-template-names.md#repos-sticky-header | | | jsdoc/convert-to-jsdoc-comments | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/convert-to-jsdoc-comments.md#repos-sticky-header | | | jsdoc/imports-as-dependencies | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/imports-as-dependencies.md#repos-sticky-header | | | jsdoc/informative-docs | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header | | | jsdoc/lines-before-block | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/lines-before-block.md#repos-sticky-header | | | jsdoc/match-description | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-description.md#repos-sticky-header | | | jsdoc/match-name | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-name.md#repos-sticky-header | | | jsdoc/no-bad-blocks | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-bad-blocks.md#repos-sticky-header | | | jsdoc/no-blank-block-descriptions | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-block-descriptions.md#repos-sticky-header | | | jsdoc/no-blank-blocks | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-blocks.md#repos-sticky-header | | | jsdoc/no-missing-syntax | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-missing-syntax.md#repos-sticky-header | | | jsdoc/no-restricted-syntax | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-restricted-syntax.md#repos-sticky-header | | | jsdoc/no-types | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-types.md#repos-sticky-header | | | jsdoc/require-asterisk-prefix | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-asterisk-prefix.md#repos-sticky-header | | | jsdoc/require-description | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description.md#repos-sticky-header | | | jsdoc/require-description-complete-sentence | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description-complete-sentence.md#repos-sticky-header | | | jsdoc/require-example | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header | | | jsdoc/require-file-overview | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header | | | jsdoc/require-hyphen-before-param-description | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header | | | jsdoc/require-template | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header | | | jsdoc/require-throws | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws.md#repos-sticky-header | | | jsdoc/sort-tags | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/sort-tags.md#repos-sticky-header | | | jsdoc/text-escaping | https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/text-escaping.md#repos-sticky-header | ✨ = Implemented, 🚫 = No need to implement

[Boshen]

The jsdoc parser is incomplete so we'll have to iteratively expand the jsdoc functionality as we add more rules.

[leaysgur]

Before begin

Unfortunately, this plugin do not seem to cover all features in its test cases for many of their rules.
You may need to actually set up the eslint and plugin to see what the behavior is like...

Just rewrite original implementation was relatively hard. I recommend to re-implement from scratch after understanding rule and its all variations if possible.

Implementation notes

• Blocking tags by settings.tagNamePreferences[name]: false is reported by only check-tag-name rule
  • In original plugin, some rules report it some are not
• Plugin settings are not fully supported
  • contexts
  • mode: we handle both JS and TS
• Rule config are not fully supported
  • contexts
  • next(and related things): for require-yields
  • publicOnly: for require-returns
  • useDefaultObjectProperties: for require-param
• Closure syntax and related features are not supported
• Tag inheritance is not supported
  • e.g. /** @ignore */ class X { /** This is not ignored */ foo() {} }
• Fixers are not implemented

Rules anatomy

Currently eslint-plugin-jsdoc has 53 rules, and they can be divided into 4 categories.

Rules to check every all comments(1 rule)

• no-bad-blocks
  • stylistic

Rules to check every JSDoc comments(27 rules)

• check-access(recommended)
• check-alignment(recommended)
  • stylistic, need original Comment indent depth
• check-property-names(recommended)
• check-types(recommended)
  • type-checked
• check-values(recommended)
  • requires semver, spdx-expression-parse
• empty-tags(recommended)
• multiline-blocks(recommended)
  • stylistic
• no-multi-asterisks(recommended)
  • stylistic
• require-property(recommended)
• require-property-description(recommended)
• require-property-name(recommended)
• require-property-type(recommended)
• tag-lines(recommended)
  • stylistic, need to parse comment content again to check lines between tags
• valid-types(recommended)
  • type-checked
• check-examples
• check-indentation
• check-line-alignment
• check-syntax
• imports-as-dependencies
• no-blank-block-descriptions
• no-blank-blocks
• require-asterisk-prefix
• require-description-complete-sentence
• require-file-overview
• require-hyphen-before-param-description
• sort-tags
• text-escaping

Rules to check every JSDoc comments + additional check with attaching node(3 rules)

• no-undefined-types(recommended)
  • type-checked
• check-tag-names(recommended)
• informative-docs
  • requires are-docs-informative

Rules to check specific nodes with attached JSDoc comments(22 rules)

• check-param-names(recommended)
• implements-on-classes(recommended)
• no-defaults(recommended)
• require-jsdoc(recommended)
  • stylistic
• require-param(recommended)
• require-param-description(recommended)
• require-param-name(recommended)
• require-param-type(recommended)
• require-returns(recommended)
• require-returns-check(recommended)
  • type-checked
• require-returns-description(recommended)
• require-returns-type(recommended)
• require-yields(recommended)
• require-yields-check(recommended)
  • type-checked
• match-description
• match-name
• no-missing-syntax
• no-restricted-syntax
• no-types
• require-description
• require-example
• require-throws

[leaysgur]

I have been working on this plugin for the past 6 months. As a personal goal, I aimed to implement rules that are recommended, not stylistic, and not type-checked.

At this time,

• Mostly achieved that
  • Except for check-param-names, which is really complex and out of control 🫠
• I am feeling somewhat burnt out

Therefore, I am considering stepping away from this issue.

If anyone is interested in taking on this challenge, feel free to ask me questions. 😉

[Boshen]

@leaysgur Thank you so much for your contribution ❤️

My intention was to implement a jsdoc parser with you, but you have blown me away with your endurance.

Please take some rest. If you feel like working on some other parts of the project, feel free to DM on twitter or discord.