Closed JoshuaKGoldberg closed 1 month ago
Despite the explanation on typescript-eslint.io I'm also unclear that these require-*
rules could really be considered "stylistic". None of our rules really impact program logic. Maybe we could come up with some other dichotomous terminology?
I think that the general issue here is the hierarchical configuration approach of eslint-plugin-jsdoc.
If I understand @JoshuaKGoldberg correctly, they basically wants to disable jsdoc/require-jsdoc
while keeping all other rules. So they wouldn't get any warning/error if there is no docstring, but they would be notified if a parameter is missing.
A similar request was asked in #1169 where they don't want have all parameters documented, but if there is a documentation it should be correct.
@JoshuaKGoldberg using flat configs, you can already inherit a default configuration. However, the issue is that if you disable some rules, others will be disabled as well, because of the rule hierarchy.
const ruleSet = [
// typescript specific rules - from https://github.com/typescript-eslint/typescript-eslint/issues/7694#issuecomment-1854655034
...compat.extends('plugin:@typescript-eslint/recommended'),
...compat.plugins('@typescript-eslint'),
// enable eslint-plugin-jsdoc rules
{
// inherit eslint-plugin-jsdoc recommended configuration
...jsdoc.configs['flat/recommended-typescript'],
// customisation:
rules: {
...jsdoc.configs['flat/recommended-typescript'].rules
'jsdoc/require-hyphen-before-param-description': 'error', // wont trigger anything, because jsdoc/require-jsdoc is off :/
'jsdoc/require-jsdoc': 'off',
},
},
]
I think that the general issue here is the hierarchical configuration approach of eslint-plugin-jsdoc. If I understand @JoshuaKGoldberg correctly, they basically wants to disable
jsdoc/require-jsdoc
while keeping all other rules.However, the issue is that if you disable some rules, others will be disabled as well, because of the rule hierarchy. ``` 'jsdoc/require-hyphen-before-param-description': 'error', // wont trigger anything, because jsdoc/require-jsdoc is off :/ 'jsdoc/require-jsdoc': 'off', ```
The rules are not actually hierarchical in this manner. If require-jsdoc
is off, require-hypen-before-param-description
will in fact trigger if there is a description present without a hyphen. Likewise can require-param
, etc. be triggered.
So, what @JoshuaKGoldberg is requesting is simply a config to automatically disable the likes of:
require-jsdoc
require-param
require-returns
require-yields
I would presume the following would also be desired for disabling:
require-param-description
require-param-type
require-param-name
require-property
require-property-description
require-property-name
require-property-type
require-returns-description
require-returns-type
This will thus not require params, properties, return statements, etc., nor their names, types, or descriptions to be present, just that if present, they are valid (according to remaining rules such as check-param-names
which insists that if there is something present like @param anArg
, that anArg
exists in the function).
There is a separate dimension here though, as to what is "stylistic". For example, jsdoc/no-multi-asterisks
is not requiring anything, but it is also a stylistic question. The proposal should really be specific as to what is the expected grouping for each rule.
In my view, it could be more helpful for us to have a few more atomic groupings (possibly even overlapping), e.g., a require
config, a stylistic config, a logically-valid config, etc.
I do something similar in my config for types-in-js workflows, that skips the documentation aspect of jsdoc: https://github.com/voxpelli/eslint-config/blob/main/base-configs/jsdoc.js
jsdoc.configs['flat/recommended-typescript-flavor'],
{
name: '@voxpelli/jsdoc',
rules: {
'jsdoc/check-types': 'off',
'jsdoc/require-jsdoc': 'off',
'jsdoc/require-param-description': 'off',
'jsdoc/require-property-description': 'off',
'jsdoc/require-returns-description': 'off',
'jsdoc/require-yields': 'off',
'jsdoc/tag-lines': ['warn', 'never', { 'startLines': 1 }],
'jsdoc/valid-types': 'off',
},
},
Something like plugin:jsdoc/recommended-typescript-typed
that does that would work well for me (also do note that its a long time since I set that up, so some options may be a bit needless nowadays)
As of #1289, jsdoc/lines-before-block
would also be disabled in that list.
recommended-typescript-typed
I like that naming!
If it helps, I'd be happy to send a PR with this, if given the 👍. 🙂
As of #1289,
jsdoc/lines-before-block
would also be disabled in that list.
Ok, so you're also talking about disabling truly stylistic items as well. But I think we should also have config which is for disabling requirements (e.g., require-param
) but which includes the default style rules (some may like to keep things clean but not be so demanding as to the presence of docs). And maybe config which disables the style rules but which doesn't disable the require-param
types (for those who want strict checking but don't care about the styling).
If it helps, I'd be happy to send a PR with this, if given the 👍. 🙂
Sure, go for it.
Thanks!
:tada: This issue has been resolved in version 50.2.0 :tada:
The release is available on:
Your semantic-release bot :package::rocket:
Motivation
I'd like to use the recommended ruleset from
eslint-plugin-jsdoc
only to enforce that JSDoc comments are correct in TypeScript repos. I don't want to enforce that they exist, just that if they do exist they're correct.Current behavior
Right now, the steps are:
plugin:jsdoc/recommended-typescript-error
jsdoc/require-*
rules (jsdoc,
param,returns
,yields
)Desired behavior
My preference would be to have a breaking change to remove those rules from
plugin:jsdoc/recommended-typescript
and put them into a new preset config likestylistic-typescript
. This would mirror how typescript-eslint has separate "stylistic" configs.Failing that, it'd be nice to have a preset config with a name like
plugin:jsdoc/logical
.Alternatives considered
Users like me can make our own shareable configs... but it'd be nice to not have to wrap around jsdoc's configs that way.