☂️ 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.