feat: add an allowOverrideWithoutParam setting for jsdoc/require-param (#74)

Author: rsimha

README.md

@@ -14,6 +14,7 @@ JSDoc linting rules for ESLint.
     * [Settings](#eslint-plugin-jsdoc-settings)
         * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
         * [Additional Tag Names](#eslint-plugin-jsdoc-settings-additional-tag-names)
+        * [Allow `@override` Without Accompanying `@param` Tags](#eslint-plugin-jsdoc-settings-allow-override-without-param)
     * [Rules](#eslint-plugin-jsdoc-rules)
         * [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
         * [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names)
@@ -148,6 +149,22 @@ Use `settings.jsdoc.additionalTagNames` to configure additional, allowed JSDoc t
 }
 ```
 
+<a name="eslint-plugin-jsdoc-settings-allow-override-without-param"></a>
+### Allow `@override` Without Accompanying `@param` Tags
+
+Use `settings.jsdoc.allowOverrideWithoutParam` to indicate whether the `@override` tag can be used without accompanying `@param` tag(s). The default value is `false`. The format of the configuration is as follows:
+
+```json
+{
+    "rules": {},
+    "settings": {
+        "jsdoc": {
+            "allowOverrideWithoutParam": true
+        }
+    }
+}
+```
+
 <a name="eslint-plugin-jsdoc-rules"></a>
 ## Rules
 
@@ -998,6 +1015,14 @@ function quux (foo, bar) {
 
 }
 // Message: Missing JSDoc @param "bar" declaration.
+
+/**
+ * @override
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @arg "foo" declaration.
 ```
 
 The following patterns are not considered problems:
@@ -1023,6 +1048,22 @@ function quux (foo) {
 function quux (foo) {
 
 }
+
+/**
+ * @override
+ * @param foo
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @override
+ */
+function quux (foo) {
+
+}
+// Settings: { "allowOverrideWithoutParam": true }
 ```
 
 

src/iterateJsdoc.js

@@ -2,7 +2,7 @@ import _ from 'lodash';
 import commentParser from 'comment-parser';
 import jsdocUtils from './jsdocUtils';
 
-const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames) => {
+const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames, allowOverrideWithoutParam) => {
   const utils = {};
 
   utils.getFunctionParameterNames = () => {
@@ -29,6 +29,10 @@ const curryUtils = (functionNode, jsdoc, tagNamePreference, additionalTagNames)
     return jsdocUtils.hasTag(jsdoc, name);
   };
 
+  utils.isOverrideAllowedWithoutParam = () => {
+    return allowOverrideWithoutParam;
+  };
+
   return utils;
 };
 
@@ -58,6 +62,7 @@ export default (iterator) => {
     const sourceCode = context.getSourceCode();
     const tagNamePreference = _.get(context, 'settings.jsdoc.tagNamePreference') || {};
     const additionalTagNames = _.get(context, 'settings.jsdoc.additionalTagNames') || {};
+    const allowOverrideWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowOverrideWithoutParam'));
 
     const checkJsdoc = (functionNode) => {
       const jsdocNode = sourceCode.getJSDocComment(functionNode);
@@ -82,7 +87,7 @@ export default (iterator) => {
         }
       };
 
-      const utils = curryUtils(functionNode, jsdoc, tagNamePreference, additionalTagNames);
+      const utils = curryUtils(functionNode, jsdoc, tagNamePreference, additionalTagNames, allowOverrideWithoutParam);
 
       iterator({
         context,

src/rules/requireParam.js

@@ -13,6 +13,12 @@ export default iterateJsdoc(({
     return;
   }
 
+  // When settings.jsdoc.allowOverrideWithoutParam is true, override implies that all documentation is inherited.
+  // See https://github.com/gajus/eslint-plugin-jsdoc/issues/73
+  if (utils.hasTag('override') && utils.isOverrideAllowedWithoutParam()) {
+    return;
+  }
+
   _.some(functionParameterNames, (functionParameterName, index) => {
     const jsdocParameterName = jsdocParameterNames[index];
 

test/rules/assertions/requireParam.js

@@ -53,6 +53,21 @@ export default {
           message: 'Missing JSDoc @param "bar" declaration.'
         }
       ]
+    },
+    {
+      code: `
+          /**
+           * @override
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "foo" declaration.'
+        }
+      ]
     }
   ],
   valid: [
@@ -92,6 +107,32 @@ export default {
           }
         }
       }
+    },
+    {
+      code: `
+          /**
+           * @override
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @override
+           */
+          function quux (foo) {
+
+          }
+      `,
+      settings: {
+        jsdoc: {
+          allowOverrideWithoutParam: true
+        }
+      }
     }
   ]
 };