fix: add enableFixer option to require-example

- Add test coverage for option
- Add option to rule
- Wrap fixer logic in a conditional
- Update readme with new option
- Fix `require-example` readme options list to match current implementation

.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`|
 
 <!-- assertions requireExample -->

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`.
 
+<a name="user-content-eslint-plugin-jsdoc-rules-require-example-options-25-enablefixer-2"></a>
+<a name="eslint-plugin-jsdoc-rules-require-example-options-25-enablefixer-2"></a>
+##### <code>enableFixer</code>
+
+A boolean on whether to enable the fixer (which adds an empty `@example` block).
+Defaults to `true`.
+
 <a name="user-content-eslint-plugin-jsdoc-rules-require-example-fixer"></a>
 <a name="eslint-plugin-jsdoc-rules-require-example-fixer"></a>
 #### 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`.
 
-<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-2"></a>
-<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-2"></a>
+<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-3"></a>
+<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-enablefixer-3"></a>
 ##### <code>enableFixer</code>
 
 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:
 
-<a name="user-content-eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-3"></a>
-<a name="eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-3"></a>
+<a name="user-content-eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-4"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-options-32-enablefixer-4"></a>
 ##### <code>enableFixer</code>
 
 Whether to enable the fixer. Defaults to `true`.

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

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