Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

☂️ eslint-plugin-jsdoc #1170

Open
camc314 opened this issue Nov 6, 2023 · 4 comments
Open

☂️ eslint-plugin-jsdoc #1170

camc314 opened this issue Nov 6, 2023 · 4 comments
Labels
A-linter Area - Linter E-Help Wanted Experience level - For the experienced collaborators

Comments

@camc314
Copy link
Contributor

camc314 commented Nov 6, 2023 •
edited by github-actions bot
Loading

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
@camc314 camc314 mentioned this issue Nov 6, 2023
Open
@camc314 camc314 changed the title https://github.com/gajus/eslint-plugin-jsdoc (recommended) ☔ linter: eslint-plugin-jsdoc (recommended) Nov 6, 2023
@camc314 camc314 added E-Help Wanted Experience level - For the experienced collaborators A-linter Area - Linter labels Nov 6, 2023
@Boshen
Copy link
Member

Boshen commented Nov 7, 2023

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

@Boshen Boshen changed the title ☔ linter: eslint-plugin-jsdoc (recommended) ☂️ linter: eslint-plugin-jsdoc Jan 26, 2024
@Boshen Boshen changed the title ☂️ linter: eslint-plugin-jsdoc ☂️ eslint-plugin-jsdoc Jan 26, 2024
@leaysgur leaysgur mentioned this issue Feb 13, 2024
Closed
@leaysgur
Copy link
Contributor

leaysgur commented Feb 26, 2024 •
edited
Loading

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)
  • 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

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

This was referenced Apr 1, 2024
Merged
Merged
Boshen pushed a commit that referenced this issue Apr 4, 2024
@leaysgur
feat(linter): Implement jsdoc/empty-tags (#2893)
6823482 
Part of #1170 

-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/empty-tags.md
-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/src/rules/emptyTags.js
Boshen pushed a commit that referenced this issue Apr 4, 2024
@leaysgur
feat(linter): Implement jsdoc/check-access (#2642)
aa63b64 
Part of #1170, Finally... 🗻 

Some preparation PRs may be needed in advance.

- [x] settings.jsdoc #2706 
- [x] new struct design #2765
- [x] handle `Span` for diagnostics #2815

Implement plugin itself.

-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-access.md
-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/src/rules/checkAccess.js

I'll send a PR to make this plugin public after confirming that a few
more rules can be implemented without any problems.
@leaysgur leaysgur mentioned this issue Apr 15, 2024
Merged
Boshen pushed a commit that referenced this issue Apr 16, 2024
@leaysgur
feat(linter): Implement plugin-jsdoc/check-property-names (#2989)
df2036e 
Part of #1170 

- Doc:
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-property-names.md#repos-sticky-header
- Test:
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/test/rules/assertions/checkPropertyNames.js
- Impl:
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/src/rules/checkPropertyNames.js
@leaysgur leaysgur mentioned this issue Apr 17, 2024
Merged
Boshen pushed a commit that referenced this issue Apr 17, 2024
@leaysgur
feat(linter/jsdoc): Implement require-property rule (#3011)
7de9c91 
Part of #1170 

- Doc:
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property.md#repos-sticky-header
- Src:
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/src/rules/requireProperty.js
- Test:
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/test/rules/assertions/requireProperty.js
@leaysgur leaysgur mentioned this issue Apr 17, 2024
Merged
Boshen pushed a commit that referenced this issue Apr 17, 2024
@leaysgur
feat(linter/jsdoc): Implement require-property-(type|name|description…
5d89e75 
…) rules (#3013)

Part of #1170 

-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-type.md
-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-name.md
-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-description.md
@leaysgur leaysgur mentioned this issue Apr 19, 2024
Merged
Boshen pushed a commit that referenced this issue Apr 23, 2024
@leaysgur
feat(linter/jsdoc): Implement check-tag-names rule (#3029)
d109767 
Part of #1170 

-
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md#user-content-check-tag-names-options-definedtags

(This time, I'm less confident that I have implemented correctly. 😓 )
@leaysgur leaysgur mentioned this issue Apr 24, 2024
Merged
Boshen pushed a commit that referenced this issue Apr 25, 2024
@leaysgur
feat(linter/jsdoc): Implement implements-on-classes rule (#3081)
fa3d9d2 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.md

`contexts` option is not supported for now.
@leaysgur leaysgur mentioned this issue Apr 25, 2024
Merged
Boshen pushed a commit that referenced this issue Apr 25, 2024
@leaysgur
feat(linter/jsdoc): Implement no-defaults rule (#3098)
5866086 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-defaults.md#repos-sticky-header
@leaysgur leaysgur mentioned this issue May 2, 2024
Merged
Boshen pushed a commit that referenced this issue May 2, 2024
@leaysgur
feat(linter/jsdoc): Implement require-yields rule (#3150)
5a1d63a 
Part of #1170 

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.md

With:

- Fix typo of JSDocPluginSettings
- Update utils/jsdoc
@leaysgur leaysgur mentioned this issue May 13, 2024
Merged
Boshen pushed a commit that referenced this issue May 23, 2024
@leaysgur
feat(linter/jsdoc): Implement require-returns rule (#3218)
3a5f088 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md
@leaysgur leaysgur mentioned this issue May 24, 2024
Merged
Boshen pushed a commit that referenced this issue May 24, 2024
@leaysgur
feat(linter/jsdoc): Implement require-returns-description (#3397)
b6e2d62 
Part of #1170 

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md
@leaysgur leaysgur mentioned this issue May 29, 2024
Merged
@leaysgur leaysgur mentioned this issue Jun 6, 2024
Merged
Boshen pushed a commit that referenced this issue Jun 6, 2024
@leaysgur
feat(linter/jsdoc): Implement require-returns-type rule (#3458)
747500a 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md
Boshen pushed a commit that referenced this issue Jun 7, 2024
@leaysgur
feat(linter/jsdoc): Implement require-param rule (#3554)
4a075cc 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md

NOTE: `config.useDefaultObjectProperties` is not implemented for now.
@leaysgur leaysgur mentioned this issue Jun 10, 2024
Merged
Boshen pushed a commit that referenced this issue Jun 10, 2024
@leaysgur
feat(linter/jsdoc): Implement require-param-type rule (#3601)
d6370f1 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-type.md
@leaysgur leaysgur mentioned this issue Jun 11, 2024
Merged
Boshen pushed a commit that referenced this issue Jun 11, 2024
@leaysgur
feat(linter/jsdoc): Implement require-param-description (#3621)
110661c 
Part of #1170

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-description.md
@leaysgur leaysgur mentioned this issue Jun 12, 2024
Merged
Boshen pushed a commit that referenced this issue Jun 12, 2024
@leaysgur
feat(linter/jsdoc): Implement require-param-name rule (#3636)
e32ce00 
Part of #1170 

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-name.md
@leaysgur
Copy link
Contributor

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
Copy link
Member

Boshen commented Jun 13, 2024

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-linter Area - Linter E-Help Wanted Experience level - For the experienced collaborators
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@Boshen @leaysgur @camc314