Make recommended or a new config with logical rules

[JoshuaKGoldberg]

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:

1. Extend from plugin:jsdoc/recommended-typescript-error
2. Manually disable 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 like stylistic-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.

[brettz9]

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?

[KilianU]

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',
    },
  },
]

[brettz9]

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.

<snip>
      'jsdoc/require-hyphen-before-param-description': 'error',  // wont trigger anything, because jsdoc/require-jsdoc is off :/
      'jsdoc/require-jsdoc': 'off',
<snip>

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.