Move settings to options #216

golopot · 2019-05-12T16:15:35Z

It is hard to find out which setting adheres to which rule. It is better to move settings specific to one rule to the option of that rule.

brettz9 · 2019-05-14T23:52:50Z

Could you change the issue title to not be specific to require-param? I think it would be better in the case of most rules to allow for options instead of settings. (There may be a few though which interact across rules.)

golopot · 2019-05-15T11:53:22Z

It seems that only require-param and check-examples have accompanied settings.

brettz9 · 2019-05-16T00:20:35Z

There are others; e.g., valid-types invokes utils.isNamepathType which, passes on the checkSeesForNamepaths setting, etc. It is a little harder to follow in the source because the settings are in iterateJsdoc and the rule pages typically interact with these settings through utils.

brettz9 · 2019-05-16T02:59:50Z

Also check-tag-names has the setting additionalTagNames which only it uses, and valid-types has two settings (allowEmptyNamepaths and checkSeesForNamepaths) that only it uses. And require-jsdoc has exemptEmptyFunctions.

require-example only has avoidExampleOnConstructors and require-returns only has forceRequireReturn.

The only setting that really is used across rules is tagNamePreference and I actually think we might change it so that it only works with check-tag-names, as the various require and param rules which use it are, because of it, failing to check for violations in non-preferred (or non-default) tags (e.g., if I prefer @param, but have a problem in @arg, it won't be caught). While this might be seen as a minor optimization if one knows one has no need to check for other synonyms, I think this is not worth it. But the option does make sense in check-tag-names.

…check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases - Fix: Remove `parameter` as accepted synonym for `@param` (not listed at site) - Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting - Refactoring: Avoid checking for preferred name for `example` (as there are no official synonyms) - Refactoring: Toward resolving gajus#216, group settings by which rules use them - Refactoring: Rename `isLink` inner function to `isInlineTag` for accuracy - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules

…check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases - Fix: Remove `parameter` as accepted synonym for `@param` (not listed at site) - Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting - Refactoring: Avoid checking for preferred name for `example` (as there are no official synonyms) - Refactoring: Toward resolving gajus#216, group settings by which rules use them - Refactoring: Rename `isLink` inner function to `isInlineTag` for accuracy - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`

…check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases - Fix: Remove `parameter` as accepted synonym for `@param` (not listed at site); affects `check-tag-names` and various param rules - Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting - Refactoring: Avoid checking for preferred name for `example` (as there are no official synonyms) - Refactoring: Toward resolving gajus#216, group settings by which rules use them - Refactoring: Rename `isLink` inner function to `isInlineTag` for accuracy - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`

…check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases - Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting - Refactoring: Avoid checking for preferred name for `example` (as there are no official synonyms) - Refactoring: Toward resolving gajus#216, group settings by which rules use them - Refactoring: Rename `isLink` inner function to `isInlineTag` for accuracy - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`

…les use them

…check-types should be checking borrows and namepath types; flesh out require-jsdoc including scopes and tags/aliases - Enhancement: Have `require-hyphen-before-param-description` check `tagNamePreference` setting - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`

…cking borrows and namepath types; expand valid-types tags in docs; flesh out require-jsdoc docs including scopes and tags/aliases - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`

…docs including scopes and tags/aliases - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags listed for rules - Docs: Observation about `Object.create(null)` and `check-types`

…iases - Docs: Toward resolving gajus#216, document which rules employ each of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags/aliases listed for rules - Docs: Observation about `Object.create(null)` and `check-types` - Docs: Add "Settings" column in rule tables to indicate applicable settings

…of the settings - Docs: Add require-jsdoc docs per gajus#208 - Docs: Fix/add to tags/aliases listed for rules - Docs: Add "Settings" column in rule tables to indicate applicable settings - Docs: Observation about `Object.create(null)` and `check-types` - Refactoring: Avoid nested `if`

golopot · 2019-06-20T18:14:28Z

What is the process for moving settings to options? I suggest we do it one-step in a major release: add options, stop reading settings, and ~~warns to stderr~~ report an error in case a removed setting is set.

brettz9 · 2019-06-22T00:55:31Z

Sounds like a fine approach to me... I have my hands pretty full now, but a PR would be welcome...

Bear in mind though re: breaking changes... As much as one doesn't wish to make breaking changes in any project, in a linting project, it can be as little total pain for a project to keep up with more frequent breaking changes and make a few incremental changes as it is to "rip off the bandage" and do it all at once, and with linting, breaking changes are far more likely (especially if one were to interpret every minor loosening or tightening as a breaking change).

With linting, particularly ESLint, one has good feedback about what is failing and why, so it doesn't generally take a lot of debugging and deep refactoring work that might be better done all at once as can be the case for non-linting API changes.

But doing it all at once does make sense here, especially as the changes are related, and it is better to increase consistency with the API.

golopot · 2019-07-07T11:59:40Z

It will be great if someone can take up remaining part of this issue, that is, move settings of check-examples to options.

brettz9 · 2019-07-07T12:43:19Z

I've started a branch to do so; just need to fix up the docs.

We might then see about removing the already-deprecated allowOverrideWithoutParam, allowImplementsWithoutParam, and allowAugmentsExtendsWithoutParam as well as changing the default of their replacements to true.

BREAKING CHANGE: The following settings have been removed and became options under `check-examples` * `settings.jsdoc.exampleCodeRegex` * `settings.jsdoc.rejectExampleCodeRegex` * `settings.jsdoc.matchingFileName` * `settings.jsdoc.baseConfig` * `settings.jsdoc.configFile` * `settings.jsdoc.eslintrcForExamples` * `settings.jsdoc.allowInlineConfig` * `settings.jsdoc.reportUnusedDisableDirectives` * `settings.jsdoc.captionRequired` * `settings.jsdoc.noDefaultExampleRules`

gajus · 2019-07-07T14:12:47Z

🎉 This issue has been resolved in version 13.0.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

* master: feat(`require-param`): remove deprecated settings `allowOverrideWithoutParam`, `allowImplementsWithoutParam`, `allowAugmentsExtendsWithoutParam` feat(`check-examples`): move settings to options (fixes gajus#216)

gajus · 2019-09-01T05:16:20Z

🎉 This issue has been resolved in version 15.9.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

gajus added the enhancement label May 12, 2019

brettz9 mentioned this issue May 15, 2019

Typescript types should be supported in jsdoc type positions #145

Open

brettz9 added a commit to brettz9/eslint-plugin-jsdoc that referenced this issue May 16, 2019

- Refactoring: Toward resolving gajus#216, group settings by which ru…

5e79e57

…les use them

brettz9 added a commit to brettz9/eslint-plugin-jsdoc that referenced this issue May 16, 2019

- Refactoring: Toward resolving gajus#216, group settings by which ru…

a52bb86

…les use them

brettz9 mentioned this issue May 16, 2019

require-hyphen-before-param-description and tagNamePreference setting #234

Merged

brettz9 mentioned this issue Jun 18, 2019

Add exported functions option to require-jsdoc rule #262

Merged

golopot changed the title ~~Move settings of require-param from plugin settings to rule option~~ Move settings to options Jun 20, 2019

golopot mentioned this issue Jul 7, 2019

Move settings to options #317

Merged

brettz9 mentioned this issue Jul 7, 2019

check-examples: change settings to options #318

Merged

brettz9 closed this as completed in #318 Jul 7, 2019

gajus added the released label Jul 7, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move settings to options #216

Move settings to options #216

golopot commented May 12, 2019

brettz9 commented May 14, 2019

golopot commented May 15, 2019

brettz9 commented May 16, 2019

brettz9 commented May 16, 2019 •

edited

Loading

golopot commented Jun 20, 2019 •

edited

Loading

brettz9 commented Jun 22, 2019 •

edited

Loading

golopot commented Jul 7, 2019

brettz9 commented Jul 7, 2019

gajus commented Jul 7, 2019

gajus commented Sep 1, 2019

Move settings to options #216

Move settings to options #216

Comments

golopot commented May 12, 2019

brettz9 commented May 14, 2019

golopot commented May 15, 2019

brettz9 commented May 16, 2019

brettz9 commented May 16, 2019 • edited Loading

golopot commented Jun 20, 2019 • edited Loading

brettz9 commented Jun 22, 2019 • edited Loading

golopot commented Jul 7, 2019

brettz9 commented Jul 7, 2019

gajus commented Jul 7, 2019

gajus commented Sep 1, 2019

brettz9 commented May 16, 2019 •

edited

Loading

golopot commented Jun 20, 2019 •

edited

Loading

brettz9 commented Jun 22, 2019 •

edited

Loading