feat(require-param): add ignoreWhenAllParamsMissing option; fixes #…

…1317
gajus · Sep 26, 2024 · 3b18435 · 3b18435
1 parent 51c68b1
commit 3b18435
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 2 deletions.
diff --git a/.README/rules/require-param.md b/.README/rules/require-param.md
@@ -369,6 +369,11 @@ documentation). Defaults to `true`.
 Set to `true` if you wish to expect documentation of properties on objects
 supplied as default values. Defaults to `false`.
 
+### `ignoreWhenAllParamsMissing`
+
+Set to `true` to ignore reporting when all params are missing. Defaults to
+`false`.
+
 ## Context and settings
 
 |          |                      |
@@ -377,7 +382,7 @@ supplied as default values. Defaults to `false`.
 | Tags     | `param` |
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
-| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `unnamedRootBase`, `useDefaultObjectProperties`|
+| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`|
 | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 ## Failing examples

diff --git a/docs/rules/require-param.md b/docs/rules/require-param.md
@@ -23,6 +23,7 @@
     * [`checkDestructured`](#user-content-require-param-options-checkdestructured)
     * [`checkDestructuredRoots`](#user-content-require-param-options-checkdestructuredroots)
     * [`useDefaultObjectProperties`](#user-content-require-param-options-usedefaultobjectproperties)
+    * [`ignoreWhenAllParamsMissing`](#user-content-require-param-options-ignorewhenallparamsmissing)
 * [Context and settings](#user-content-require-param-context-and-settings)
 * [Failing examples](#user-content-require-param-failing-examples)
 * [Passing examples](#user-content-require-param-passing-examples)
@@ -437,6 +438,13 @@ documentation). Defaults to `true`.
 Set to `true` if you wish to expect documentation of properties on objects
 supplied as default values. Defaults to `false`.
 
+<a name="user-content-require-param-options-ignorewhenallparamsmissing"></a>
+<a name="require-param-options-ignorewhenallparamsmissing"></a>
+### <code>ignoreWhenAllParamsMissing</code>
+
+Set to `true` to ignore reporting when all params are missing. Defaults to
+`false`.
+
 <a name="user-content-require-param-context-and-settings"></a>
 <a name="require-param-context-and-settings"></a>
 ## Context and settings
@@ -447,7 +455,7 @@ supplied as default values. Defaults to `false`.
 | Tags     | `param` |
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
-| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `unnamedRootBase`, `useDefaultObjectProperties`|
+| Options  |`autoIncrementBase`, `checkConstructors`, `checkDestructured`, `checkDestructuredRoots`, `checkGetters`, `checkRestProperty`, `checkSetters`, `checkTypesPattern`, `contexts`, `enableFixer`, `enableRestElementFixer`, `enableRootFixer`, `exemptedBy`, `ignoreWhenAllParamsMissing`, `unnamedRootBase`, `useDefaultObjectProperties`|
 | Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <a name="user-content-require-param-failing-examples"></a>
@@ -1162,6 +1170,14 @@ class A {
   }
 }
 // Message: Missing JSDoc @param "root1" declaration.
+
+/**
+ * Some desc.
+ * @param a
+ */
+function quux (a, b) {}
+// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}]
+// Message: Missing JSDoc @param "b" declaration.
 ````
 
 
@@ -1813,5 +1829,11 @@ const inner = (c: number, d: string): void => {
   console.log(d);
 };
 // Settings: {"jsdoc":{"contexts":["VariableDeclaration"]}}
+
+/**
+ * Some desc.
+ */
+function quux (a, b) {}
+// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}]
 ````
 
diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
@@ -60,6 +60,7 @@ export default iterateJsdoc(({
       'root',
     ],
     useDefaultObjectProperties = false,
+    ignoreWhenAllParamsMissing = false,
   } = context.options[0] || {};
 
   const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
@@ -83,6 +84,10 @@ export default iterateJsdoc(({
      * }[]}
      */ (utils.getJsdocTagsDeep(preferredTagName));
 
+  if (ignoreWhenAllParamsMissing && !jsdocParameterNames.length) {
+    return;
+  }
+
   const shallowJsdocParameterNames = jsdocParameterNames.filter((tag) => {
     return !tag.name.includes('.');
   }).map((tag, idx) => {
@@ -571,6 +576,9 @@ export default iterateJsdoc(({
             },
             type: 'array',
           },
+          ignoreWhenAllParamsMissing: {
+            type: 'boolean',
+          },
           unnamedRootBase: {
             items: {
               type: 'string',

diff --git a/test/rules/assertions/requireParam.js b/test/rules/assertions/requireParam.js
@@ -2527,6 +2527,33 @@ export default {
         }
       `,
     },
+    {
+      code: `
+        /**
+         * Some desc.
+         * @param a
+         */
+        function quux (a, b) {}
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @param "b" declaration.',
+        },
+      ],
+      options: [
+        {
+          ignoreWhenAllParamsMissing: true,
+        }
+      ],
+      output: `
+        /**
+         * Some desc.
+         * @param a
+         * @param b
+         */
+        function quux (a, b) {}
+      `,
+    },
   ],
   valid: [
     {
@@ -3604,5 +3631,18 @@ export default {
         }
       },
     },
+    {
+      code: `
+        /**
+         * Some desc.
+         */
+        function quux (a, b) {}
+      `,
+      options: [
+        {
+          ignoreWhenAllParamsMissing: true,
+        }
+      ],
+    },
   ],
 };