feat(require-example): add exemptNoArguments option (#634)

* feat(`require-example`): add `exemptNoArguments` option

* docs(`require-example`): add `exemptNoArguments`

Author: brettz9

.README/rules/require-example.md

@@ -18,6 +18,11 @@ block avoids the need for an `@example`. Defaults to an array with
 so be sure to add back `inheritdoc` if you wish its presence to cause
 exemption of the rule.
 
+##### `exemptNoArguments`
+
+Boolean to indicate that no-argument functions should not be reported for
+missing `@example` declarations.
+
 ##### `contexts`
 
 Set this to an array of strings representing the AST context
@@ -50,7 +55,7 @@ report a missing example description after this is added.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|`example`|
-|Options|`exemptedBy`, `avoidExampleOnConstructors`, `contexts`|
+|Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
 |Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <!-- assertions requireExample -->

README.md

@@ -8162,6 +8162,12 @@ block avoids the need for an `@example`. Defaults to an array with
 so be sure to add back `inheritdoc` if you wish its presence to cause
 exemption of the rule.
 
+<a name="eslint-plugin-jsdoc-rules-require-example-options-18-exemptnoarguments"></a>
+##### <code>exemptNoArguments</code>
+
+Boolean to indicate that no-argument functions should not be reported for
+missing `@example` declarations.
+
 <a name="eslint-plugin-jsdoc-rules-require-example-options-18-contexts-4"></a>
 ##### <code>contexts</code>
 
@@ -8199,7 +8205,7 @@ report a missing example description after this is added.
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|`example`|
-|Options|`exemptedBy`, `avoidExampleOnConstructors`, `contexts`|
+|Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
 |Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 The following patterns are considered problems:
@@ -8213,6 +8219,15 @@ function quux () {
 }
 // Message: Missing JSDoc @example declaration.
 
+/**
+ *
+ */
+function quux (someParam) {
+
+}
+// Options: [{"exemptNoArguments":true}]
+// Message: Missing JSDoc @example declaration.
+
 /**
  *
  */
@@ -8442,6 +8457,14 @@ class TestClass {
   set Test(value) { }
 }
 // Options: [{"checkSetters":true}]
+
+/**
+ *
+ */
+function quux () {
+
+}
+// Options: [{"exemptNoArguments":true}]
 ````
 
 

src/iterateJsdoc.js

@@ -196,6 +196,10 @@ const getUtils = (
     return jsdocUtils.getFunctionParameterNames(node);
   };
 
+  utils.hasParams = () => {
+    return jsdocUtils.hasParams(node);
+  };
+
   utils.isConstructor = () => {
     return jsdocUtils.isConstructor(node);
   };

src/jsdocUtils.js

@@ -188,6 +188,11 @@ const getFunctionParameterNames = (functionNode : Object) : Array<T> => {
   });
 };
 
+const hasParams = (functionNode) => {
+  // Should also check `functionNode.value.params` if supporting `MethodDefinition`
+  return functionNode.params.length;
+};
+
 /**
  * Gets all names of the target type, including those that refer to a path, e.g.
  * "@param foo; @param foo.bar".
@@ -736,6 +741,7 @@ export default {
   getTagStructureForMode,
   hasATag,
   hasDefinedTypeReturnTag,
+  hasParams,
   hasReturnValue,
   hasTag,
   hasThrowValue,

src/rules/requireExample.js

@@ -2,6 +2,7 @@ import _ from 'lodash';
 import iterateJsdoc from '../iterateJsdoc';
 
 export default iterateJsdoc(({
+  context,
   jsdoc,
   report,
   utils,
@@ -10,13 +11,23 @@ export default iterateJsdoc(({
     return;
   }
 
+  const {
+    exemptNoArguments = false,
+  } = context.options[0] || {};
+
   const targetTagName = 'example';
 
   const functionExamples = _.filter(jsdoc.tags, {
     tag: targetTagName,
   });
 
   if (!functionExamples.length) {
+    if (exemptNoArguments && utils.isIteratingFunction() &&
+      !utils.hasParams()
+    ) {
+      return;
+    }
+
     utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
       if (!jsdoc.tags) {
         jsdoc.tags = [];
@@ -78,6 +89,10 @@ export default iterateJsdoc(({
             },
             type: 'array',
           },
+          exemptNoArguments: {
+            default: false,
+            type: 'boolean',
+          },
         },
         type: 'object',
       },

test/rules/assertions/requireExample.js

@@ -23,6 +23,34 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux (someParam) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @example declaration.',
+        },
+      ],
+      options: [
+        {
+          exemptNoArguments: true,
+        },
+      ],
+      output: `
+          /**
+           * @example
+           */
+          function quux (someParam) {
+
+          }
+      `,
+    },
     {
       code: `/**
  *
@@ -499,5 +527,20 @@ function quux () {
         },
       ],
     },
+    {
+      code: `
+      /**
+       *
+       */
+      function quux () {
+
+      }
+      `,
+      options: [
+        {
+          exemptNoArguments: true,
+        },
+      ],
+    },
   ],
 };