- Enhancement: Add new boolean options allowImplementsWithoutParam …

…and `allowAugmentsExtendsWithoutParam` and apply to `requireParam` (fixes gajus#100)
brettz9 · Dec 7, 2018 · 8d16526 · 8d16526
1 parent 559b287
commit 8d16526
Show file tree

Hide file tree

Showing 3 changed files with 155 additions and 2 deletions.
diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -2,7 +2,11 @@ import _ from 'lodash';
 import commentParser from 'comment-parser';
 import jsdocUtils from './jsdocUtils';
 
-const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames, allowOverrideWithoutParam) => {
+const curryUtils = (
+  functionNode, jsdoc, tagNamePreference, additionalTagNames,
+  allowOverrideWithoutParam, allowImplementsWithoutParam,
+  allowAugmentsExtendsWithoutParam
+) => {
   const utils = {};
 
   utils.getFunctionParameterNames = () => {
@@ -33,6 +37,14 @@ const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames,
     return allowOverrideWithoutParam;
   };
 
+  utils.isImplementsAllowedWithoutParam = () => {
+    return allowImplementsWithoutParam;
+  };
+
+  utils.isAugmentsExtendsAllowedWithoutParam = () => {
+    return allowAugmentsExtendsWithoutParam;
+  };
+
   return utils;
 };
 
@@ -61,6 +73,8 @@ export default (iterator) => {
     const tagNamePreference = _.get(context, 'settings.jsdoc.tagNamePreference') || {};
     const additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};
     const allowOverrideWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowOverrideWithoutParam'));
+    const allowImplementsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowImplementsWithoutParam'));
+    const allowAugmentsExtendsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowAugmentsExtendsWithoutParam'));
 
     const checkJsdoc = (functionNode) => {
       const jsdocNode = sourceCode.getJSDocComment(functionNode);
@@ -100,7 +114,11 @@ export default (iterator) => {
         }
       };
 
-      const utils = curryUtils(functionNode, jsdoc, tagNamePreference, additionalTagNames, allowOverrideWithoutParam);
+      const utils = curryUtils(
+        functionNode, jsdoc, tagNamePreference, additionalTagNames,
+        allowOverrideWithoutParam, allowImplementsWithoutParam,
+        allowAugmentsExtendsWithoutParam
+      );
 
       iterator({
         context,

diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
@@ -19,6 +19,18 @@ export default iterateJsdoc(({
     return;
   }
 
+  // When settings.jsdoc.allowImplementsWithoutParam is true, implements implies that all documentation is inherited.
+  // See https://github.com/gajus/eslint-plugin-jsdoc/issues/100
+  if (utils.hasTag('implements') && utils.isImplementsAllowedWithoutParam()) {
+    return;
+  }
+
+  // When settings.jsdoc.allowAugmentsExtendsWithoutParam is true, augments or extends implies that all documentation is inherited.
+  // See https://github.com/gajus/eslint-plugin-jsdoc/issues/100
+  if ((utils.hasTag('augments') || utils.hasTag('extends')) && utils.isAugmentsExtendsAllowedWithoutParam()) {
+    return;
+  }
+
   _.some(functionParameterNames, (functionParameterName, index) => {
     const jsdocParameterName = jsdocParameterNames[index];
 

diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
@@ -66,6 +66,51 @@ export default {
           message: 'Missing JSDoc @param "foo" declaration.'
         }
       ]
+    },
+    {
+      code: `
+          /**
+           * @implements
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "foo" declaration.'
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           * @augments
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "foo" declaration.'
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           * @extends
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "foo" declaration.'
+        }
+      ]
     }
   ],
   valid: [
@@ -131,6 +176,84 @@ export default {
           allowOverrideWithoutParam: true
         }
       }
+    },
+    {
+      code: `
+          /**
+           * @implements
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          allowImplementsWithoutParam: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           * @implements
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @augments
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          allowAugmentsExtendsWithoutParam: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           * @augments
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @extends
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          allowAugmentsExtendsWithoutParam: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           * @extends
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `
     }
   ]
 };