fix(require-example): add fixer for missing declaration (though can d…

…o nothing with missing description); fixes part of #336
gajus · Jul 22, 2019 · a45f41c · a45f41c
1 parent 5863029
commit a45f41c
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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
@@ -13,7 +13,15 @@ export default {
         {
           message: 'Missing JSDoc @example declaration.'
         }
-      ]
+      ],
+      output: `
+          /**
+           * @example
+           */
+          function quux () {
+
+          }
+      `
     },
     {
       code: `