From a45f41c5970f1bfb8f85b683c0069a0480769bca Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Sun, 21 Jul 2019 19:04:28 -0700
Subject: [PATCH] fix(require-example): add fixer for missing declaration
 (though can do nothing with missing description); fixes part of #336

---
 .README/rules/require-example.md        |  5 +++++
 README.md                               |  6 ++++++
 src/rules/requireExample.js             | 16 +++++++++++++++-
 test/rules/assertions/requireExample.js | 10 +++++++++-
 4 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/.README/rules/require-example.md b/.README/rules/require-example.md
index e49cf0b0b..9e90b5133 100644
--- a/.README/rules/require-example.md
+++ b/.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|
diff --git a/README.md b/README.md
index 7a7a52db5..81c049265 100644
--- a/README.md
+++ b/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|
diff --git a/src/rules/requireExample.js b/src/rules/requireExample.js
index 819ea695c..a710d244d 100644
--- a/src/rules/requireExample.js
+++ b/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,
diff --git a/test/rules/assertions/requireExample.js b/test/rules/assertions/requireExample.js
index 45f7454c4..5f9c85493 100644
--- a/test/rules/assertions/requireExample.js
+++ b/test/rules/assertions/requireExample.js
@@ -13,7 +13,15 @@ export default {
         {
           message: 'Missing JSDoc @example declaration.'
         }
-      ]
+      ],
+      output: `
+          /**
+           * @example
+           */
+          function quux () {
+
+          }
+      `
     },
     {
       code: `