feat(require-example): add exemptNoArguments option

Author: brettz9

README.md

@@ -8213,6 +8213,15 @@ function quux () {
 }
 // Message: Missing JSDoc @example declaration.
 
+/**
+ *
+ */
+function quux (someParam) {
+
+}
+// Options: [{"exemptNoArguments":true}]
+// Message: Missing JSDoc @example declaration.
+
 /**
  *
  */
@@ -8442,6 +8451,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,
+        },
+      ],
+    },
   ],
 };