diff --git a/.README/rules/require-example.md b/.README/rules/require-example.md index 2f98ec305..693056dcf 100644 --- a/.README/rules/require-example.md +++ b/.README/rules/require-example.md @@ -47,6 +47,11 @@ A value indicating whether getters should be checked. Defaults to `false`. A value indicating whether setters should be checked. Defaults to `false`. +##### `enableFixer` + +A boolean on whether to enable the fixer (which adds an empty `@example` block). +Defaults to `true`. + #### Fixer The fixer for `require-example` will add an empty `@example`, but it will still @@ -57,7 +62,7 @@ report a missing example description after this is added. |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled| |Tags|`example`| |Recommended|false| -|Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`| +|Options|`exemptedBy`, `exemptNoArguments`, `contexts`, `checkConstructors`, `checkGetters`, `checkSetters`, `enableFixer`| |Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| diff --git a/README.md b/README.md index 8bf058b9a..af3902c81 100644 --- a/README.md +++ b/README.md @@ -11939,6 +11939,13 @@ A value indicating whether getters should be checked. Defaults to `false`. A value indicating whether setters should be checked. Defaults to `false`. + + +##### enableFixer + +A boolean on whether to enable the fixer (which adds an empty `@example` block). +Defaults to `true`. + #### Fixer @@ -11951,7 +11958,7 @@ report a missing example description after this is added. |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled| |Tags|`example`| |Recommended|false| -|Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`| +|Options|`exemptedBy`, `exemptNoArguments`, `contexts`, `checkConstructors`, `checkGetters`, `checkSetters`, `enableFixer`| |Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`| The following patterns are considered problems: @@ -12065,6 +12072,24 @@ class TestClass { } // "jsdoc/require-example": ["error"|"warn", {"checkSetters":true}] // Message: Missing JSDoc @example description. + +/** + * + */ +function quux (someParam) { + +} +// "jsdoc/require-example": ["error"|"warn", {"enableFixer":true}] +// Message: Missing JSDoc @example declaration. + +/** + * + */ +function quux (someParam) { + +} +// "jsdoc/require-example": ["error"|"warn", {"enableFixer":false}] +// Message: Missing JSDoc @example declaration. ```` The following patterns are not considered problems: @@ -12852,8 +12877,8 @@ setters should be checked but only when there is no getter. This may be useful if one only wishes documentation on one of the two accessors. Defaults to `false`. - - + + ##### enableFixer A boolean on whether to enable the fixer (which adds an empty jsdoc block). @@ -15030,8 +15055,8 @@ function signature, it may appear that there is an actual property named An options object accepts the following optional properties: - - + + ##### enableFixer Whether to enable the fixer. Defaults to `true`. diff --git a/src/rules/requireExample.js b/src/rules/requireExample.js index 50b6b4141..68cd3b5fc 100644 --- a/src/rules/requireExample.js +++ b/src/rules/requireExample.js @@ -11,6 +11,7 @@ export default iterateJsdoc(({ } const { + enableFixer = true, exemptNoArguments = false, } = context.options[0] || {}; @@ -30,7 +31,9 @@ export default iterateJsdoc(({ } utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => { - utils.addTag(targetTagName); + if (enableFixer) { + utils.addTag(targetTagName); + } }); return; @@ -92,6 +95,10 @@ export default iterateJsdoc(({ }, type: 'array', }, + enableFixer: { + default: true, + type: 'boolean', + }, exemptedBy: { items: { type: 'string', diff --git a/test/rules/assertions/requireExample.js b/test/rules/assertions/requireExample.js index 0e8451df6..9bbe13c84 100644 --- a/test/rules/assertions/requireExample.js +++ b/test/rules/assertions/requireExample.js @@ -326,6 +326,65 @@ function quux () { }, ], }, + { + code: ` + /** + * + */ + function quux (someParam) { + + } + `, + errors: [ + { + line: 2, + message: 'Missing JSDoc @example declaration.', + }, + ], + options: [ + { + enableFixer: true, + }, + ], + output: ` + /** + * + * @example + */ + function quux (someParam) { + + } + `, + }, + { + code: ` + /** + * + */ + function quux (someParam) { + + } + `, + errors: [ + { + line: 2, + message: 'Missing JSDoc @example declaration.', + }, + ], + options: [ + { + enableFixer: false, + }, + ], + output: ` + /** + * + */ + function quux (someParam) { + + } + `, + }, ], valid: [ {