fix(require-example): add fixer for missing declaration (though can do nothing with missing description); fixes part of gajus#336

Author: brettz9

.README/rules/require-example.md

@@ -26,6 +26,11 @@ Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
 Overrides the default contexts (see below).
 
+#### Fixer
+
+The fixer for `require-example` will add an empty `@example`, but it will still
+report a missing example description after this is added.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|

README.md

@@ -4441,6 +4441,12 @@ Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
 Overrides the default contexts (see below).
 
+<a name="eslint-plugin-jsdoc-rules-require-example-fixer"></a>
+#### Fixer
+
+The fixer for `require-example` will add an empty `@example`, but it will still
+report a missing example description after this is added.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|

src/rules/requireExample.js

@@ -33,7 +33,20 @@ export default iterateJsdoc(({
   }
 
   if (!functionExamples.length) {
-    report(`Missing JSDoc @${targetTagName} declaration.`);
+    utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
+      if (!jsdoc.tags) {
+        jsdoc.tags = [];
+      }
+      const line = jsdoc.tags.length ? jsdoc.tags[jsdoc.tags.length - 1].line + 1 : 0;
+      jsdoc.tags.push({
+        description: '',
+        line,
+        name: '',
+        optional: false,
+        tag: targetTagName,
+        type: ''
+      });
+    });
 
     return;
   }
@@ -48,6 +61,7 @@ export default iterateJsdoc(({
 }, {
   contextDefaults: true,
   meta: {
+    fixable: 'code',
     schema: [
       {
         additionalProperties: false,

test/rules/assertions/requireExample.js

@@ -13,7 +13,15 @@ export default {
         {
           message: 'Missing JSDoc @example declaration.'
         }
-      ]
+      ],
+      output: `
+          /**
+           * @example
+           */
+          function quux () {
+
+          }
+      `
     },
     {
       code: `