diff --git a/.README/README.md b/.README/README.md index 0889807ea..3e6144f50 100644 --- a/.README/README.md +++ b/.README/README.md @@ -316,13 +316,14 @@ This setting is utilized by the the rule for tag name checking - `require-returns-description` - `require-returns-type` -### `@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns` +### `@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields` The following settings allows the element(s) they reference to be omitted on the JSDoc comment block of the function or that of its parent class for any of the "require" rules (i.e., `require-param`, `require-description`, -`require-example`, or `require-returns`). +`require-example`, `require-returns`, `require-throws`, `require-yields`). +* `settings.jsdoc.ignoreReplacesDocs` (`@ignore`) - Defaults to `true` * `settings.jsdoc.overrideReplacesDocs` (`@override`) - Defaults to `true` * `settings.jsdoc.augmentsExtendsReplacesDocs` (`@augments` or its alias `@extends`) - Defaults to `false`. @@ -335,6 +336,7 @@ The format of the configuration is as follows: "rules": {}, "settings": { "jsdoc": { + "ignoreReplacesDocs": true, "overrideReplacesDocs": true, "augmentsExtendsReplacesDocs": true, "implementsReplacesDocs": true diff --git a/.README/rules/require-description.md b/.README/rules/require-description.md index 1d9e9f6ba..39ec7d507 100644 --- a/.README/rules/require-description.md +++ b/.README/rules/require-description.md @@ -39,6 +39,6 @@ An options object may have any of the following properties: | Aliases | `desc` | | Recommended | false | | Options | `contexts`, `exemptedBy`, `descriptionStyle`, `checkConstructors`, `checkGetters`, `checkSetters` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | diff --git a/.README/rules/require-example.md b/.README/rules/require-example.md index ed0a3e168..2f98ec305 100644 --- a/.README/rules/require-example.md +++ b/.README/rules/require-example.md @@ -58,6 +58,6 @@ report a missing example description after this is added. |Tags|`example`| |Recommended|false| |Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`| -|Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| +|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| diff --git a/.README/rules/require-param.md b/.README/rules/require-param.md index b1472e9ea..1944309c4 100644 --- a/.README/rules/require-param.md +++ b/.README/rules/require-param.md @@ -374,6 +374,6 @@ supplied as default values. Defaults to `false`. | Aliases | `arg`, `argument` | |Recommended | true| | Options | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`, `useDefaultObjectProperties`| -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| diff --git a/.README/rules/require-returns.md b/.README/rules/require-returns.md index 15c140f6e..9e02689ac 100644 --- a/.README/rules/require-returns.md +++ b/.README/rules/require-returns.md @@ -48,6 +48,6 @@ Will also report if multiple `@returns` tags are present. | Aliases | `return` | |Recommended|true| | Options | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | diff --git a/.README/rules/require-throws.md b/.README/rules/require-throws.md index 1b9605aea..5282f3830 100644 --- a/.README/rules/require-throws.md +++ b/.README/rules/require-throws.md @@ -29,6 +29,6 @@ Requires that throw statements are documented. | Aliases | `exception` | |Recommended|true| | Options | `contexts`, `exemptedBy` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | diff --git a/.README/rules/require-yields.md b/.README/rules/require-yields.md index 8d3f092a5..2d889f284 100644 --- a/.README/rules/require-yields.md +++ b/.README/rules/require-yields.md @@ -62,6 +62,6 @@ option to expect a non-standard `@next` tag. |Aliases|`yield`| |Recommended|true| | Options | `contexts`, `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | diff --git a/README.md b/README.md index f594c5b6d..faadd44f5 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ JSDoc linting rules for ESLint. * [`maxLines` and `minLines`](#eslint-plugin-jsdoc-settings-maxlines-and-minlines) * [Mode](#eslint-plugin-jsdoc-settings-mode) * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference) - * [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns) + * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields) * [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types) * [`structuredTags`](#eslint-plugin-jsdoc-settings-structuredtags) * [Advanced](#eslint-plugin-jsdoc-advanced) @@ -389,14 +389,15 @@ This setting is utilized by the the rule for tag name checking - `require-returns-description` - `require-returns-type` - -### @override/@augments/@extends/@implements Without Accompanying @param/@description/@example/@returns + +### @override/@augments/@extends/@implements/@ignore Without Accompanying @param/@description/@example/@returns/@throws/@yields The following settings allows the element(s) they reference to be omitted on the JSDoc comment block of the function or that of its parent class for any of the "require" rules (i.e., `require-param`, `require-description`, -`require-example`, or `require-returns`). +`require-example`, `require-returns`, `require-throws`, `require-yields`). +* `settings.jsdoc.ignoreReplacesDocs` (`@ignore`) - Defaults to `true` * `settings.jsdoc.overrideReplacesDocs` (`@override`) - Defaults to `true` * `settings.jsdoc.augmentsExtendsReplacesDocs` (`@augments` or its alias `@extends`) - Defaults to `false`. @@ -409,6 +410,7 @@ The format of the configuration is as follows: "rules": {}, "settings": { "jsdoc": { + "ignoreReplacesDocs": true, "overrideReplacesDocs": true, "augmentsExtendsReplacesDocs": true, "implementsReplacesDocs": true @@ -10747,7 +10749,7 @@ An options object may have any of the following properties: | Aliases | `desc` | | Recommended | false | | Options | `contexts`, `exemptedBy`, `descriptionStyle`, `checkConstructors`, `checkGetters`, `checkSetters` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | The following patterns are considered problems: @@ -11326,7 +11328,7 @@ report a missing example description after this is added. |Tags|`example`| |Recommended|false| |Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`| -|Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| +|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| The following patterns are considered problems: @@ -14531,7 +14533,7 @@ supplied as default values. Defaults to `false`. | Aliases | `arg`, `argument` | |Recommended | true| | Options | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`, `useDefaultObjectProperties`| -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| The following patterns are considered problems: @@ -14723,6 +14725,15 @@ function quux (foo) { // Settings: {"jsdoc":{"overrideReplacesDocs":false}} // Message: Missing JSDoc @param "foo" declaration. +/** + * @ignore + */ +function quux (foo) { + +} +// Settings: {"jsdoc":{"ignoreReplacesDocs":false}} +// Message: Missing JSDoc @param "foo" declaration. + /** * @implements */ @@ -14762,6 +14773,20 @@ class A { // Settings: {"jsdoc":{"overrideReplacesDocs":false}} // Message: Missing JSDoc @param "foo" declaration. +/** + * @ignore + */ +class A { + /** + * + */ + quux (foo) { + + } +} +// Settings: {"jsdoc":{"ignoreReplacesDocs":false}} +// Message: Missing JSDoc @param "foo" declaration. + /** * @implements */ @@ -15302,6 +15327,14 @@ function quux (foo) { } // Settings: {"jsdoc":{"overrideReplacesDocs":true}} +/** + * @ignore + */ +function quux (foo) { + +} +// Settings: {"jsdoc":{"ignoreReplacesDocs":true}} + /** * @implements */ @@ -15410,6 +15443,19 @@ class A { } // Settings: {"jsdoc":{"overrideReplacesDocs":true}} +/** + * @ignore + */ +class A { + /** + * + */ + quux (foo) { + + } +} +// Settings: {"jsdoc":{"ignoreReplacesDocs":true}} + /** * @implements */ @@ -17011,7 +17057,7 @@ Will also report if multiple `@returns` tags are present. | Aliases | `return` | |Recommended|true| | Options | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | The following patterns are considered problems: @@ -18055,7 +18101,7 @@ Requires that throw statements are documented. | Aliases | `exception` | |Recommended|true| | Options | `contexts`, `exemptedBy` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | The following patterns are considered problems: @@ -18365,7 +18411,7 @@ option to expect a non-standard `@next` tag. |Aliases|`yield`| |Recommended|true| | Options | `contexts`, `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` | -| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | +| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` | The following patterns are considered problems: diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js index 9be151131..5b52dde27 100644 --- a/src/iterateJsdoc.js +++ b/src/iterateJsdoc.js @@ -78,6 +78,7 @@ const getUtils = ( const { tagNamePreference, overrideReplacesDocs, + ignoreReplacesDocs, implementsReplacesDocs, augmentsExtendsReplacesDocs, maxLines, @@ -439,6 +440,8 @@ const getUtils = ( utils.avoidDocs = () => { if ( + ignoreReplacesDocs !== false && + (utils.hasTag('ignore') || utils.classHasTag('ignore')) || overrideReplacesDocs !== false && (utils.hasTag('override') || utils.classHasTag('override')) || implementsReplacesDocs !== false && @@ -651,8 +654,10 @@ const getSettings = (context) => { // `check-types`, `no-undefined-types`, `valid-types` structuredTags: context.settings.jsdoc?.structuredTags ?? {}, - // `require-param`, `require-description`, `require-example`, `require-returns` + // `require-param`, `require-description`, `require-example`, + // `require-returns`, `require-throw`, `require-yields` overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs, + ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs, implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs, augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs, diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js index ae5719057..14d73dd52 100644 --- a/test/rules/assertions/requireParam.js +++ b/test/rules/assertions/requireParam.js @@ -700,6 +700,36 @@ export default { }, }, }, + { + code: ` + /** + * @ignore + */ + function quux (foo) { + + } + `, + errors: [ + { + line: 2, + message: 'Missing JSDoc @param "foo" declaration.', + }, + ], + output: ` + /** + * @param foo + * @ignore + */ + function quux (foo) { + + } + `, + settings: { + jsdoc: { + ignoreReplacesDocs: false, + }, + }, + }, { code: ` /** @@ -819,6 +849,45 @@ export default { }, }, }, + { + code: ` + /** + * @ignore + */ + class A { + /** + * + */ + quux (foo) { + + } + } + `, + errors: [ + { + line: 6, + message: 'Missing JSDoc @param "foo" declaration.', + }, + ], + output: ` + /** + * @ignore + */ + class A { + /** + * @param foo + */ + quux (foo) { + + } + } + `, + settings: { + jsdoc: { + ignoreReplacesDocs: false, + }, + }, + }, { code: ` /** @@ -2412,6 +2481,21 @@ export default { }, }, }, + { + code: ` + /** + * @ignore + */ + function quux (foo) { + + } + `, + settings: { + jsdoc: { + ignoreReplacesDocs: true, + }, + }, + }, { code: ` /** @@ -2580,6 +2664,26 @@ export default { }, }, }, + { + code: ` + /** + * @ignore + */ + class A { + /** + * + */ + quux (foo) { + + } + } + `, + settings: { + jsdoc: { + ignoreReplacesDocs: true, + }, + }, + }, { code: ` /**