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: [
{