.README/rules/check-param-names.md

@@ -1,6 +1,7 @@
 ### `check-param-names`
 
-Ensures that parameter names in JSDoc match those in the function declaration.
+Ensures that parameter names in JSDoc are matched by corresponding items in
+the function declaration.
 
 #### Destructuring
 

.README/rules/require-param-description.md

@@ -2,8 +2,26 @@
 
 Requires that each `@param` tag has a `description` value.
 
+Will exempt destructured roots and their children if
+`settings.exemptDestructuredRootsFromChecks` is set to `true` (e.g.,
+`@param {object} props` will be exempted from requiring a description given
+`function someFunc ({child1, child2})`).
+
 #### Options
 
+##### `setDefaultDestructuredRootDescription`
+
+Whether to set a default destructured root description. For example, you may
+wish to avoid manually having to set the description for a `@param`
+corresponding to a destructured root object as it should always be the same
+type of object. Uses `defaultDestructuredRootDescription` for the description
+string. Defaults to `false`.
+
+##### `defaultDestructuredRootDescription`
+
+The description string to set by default for destructured roots. Defaults to
+"The root object".
+
 ##### `contexts`
 
 Set this to an array of strings representing the AST context (or an object with
@@ -23,6 +41,7 @@ section of our README for more on the expected format.
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 |Recommended|true|
-|Options|`contexts`|
+|Options|`setDefaultDestructuredRootDescription`, `defaultDestructuredRootDescription`, `contexts`|
+|Settings|`exemptDestructuredRootsFromChecks`|
 
 <!-- assertions requireParamDescription -->

.README/rules/require-param-type.md

@@ -2,8 +2,25 @@
 
 Requires that each `@param` tag has a `type` value.
 
+Will exempt destructured roots and their children if
+`settings.exemptDestructuredRootsFromChecks` is set to `true` (e.g.,
+`@param props` will be exempted from requiring a type given
+`function someFunc ({child1, child2})`).
+
 #### Options
 
+##### `setDefaultDestructuredRootType`
+
+Whether to set a default destructured root type. For example, you may wish
+to avoid manually having to set the type for a `@param`
+corresponding to a destructured root object as it is always going to be an
+object. Uses `defaultDestructuredRootType` for the type string. Defaults to
+`false`.
+
+##### `defaultDestructuredRootType`
+
+The type string to set by default for destructured roots. Defaults to "object".
+
 ##### `contexts`
 
 Set this to an array of strings representing the AST context (or an object with
@@ -23,6 +40,7 @@ section of our README for more on the expected format.
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 |Recommended|true|
-|Options|`contexts`|
+|Options|`setDefaultDestructuredRootType`, `defaultDestructuredRootType`, `contexts`|
+|Settings|`exemptDestructuredRootsFromChecks`|
 
 <!-- assertions requireParamType -->

.README/rules/require-param.md

@@ -23,7 +23,7 @@ function quux ({foo: bar, baz: bax = 5}) {
 }
 ```
 
-..the fixed jsdoc will be:
+...the fixed jsdoc will be:
 
 ```js
 /**

README.md

@@ -2788,7 +2788,8 @@ const fn = ( a, b ) => {};
 <a name="eslint-plugin-jsdoc-rules-check-param-names"></a>
 ### <code>check-param-names</code>
 
-Ensures that parameter names in JSDoc match those in the function declaration.
+Ensures that parameter names in JSDoc are matched by corresponding items in
+the function declaration.
 
 <a name="user-content-eslint-plugin-jsdoc-rules-check-param-names-destructuring"></a>
 <a name="eslint-plugin-jsdoc-rules-check-param-names-destructuring"></a>
@@ -14771,10 +14772,32 @@ class A {
 
 Requires that each `@param` tag has a `description` value.
 
+Will exempt destructured roots and their children if
+`settings.exemptDestructuredRootsFromChecks` is set to `true` (e.g.,
+`@param {object} props` will be exempted from requiring a description given
+`function someFunc ({child1, child2})`).
+
 <a name="user-content-eslint-plugin-jsdoc-rules-require-param-description-options-29"></a>
 <a name="eslint-plugin-jsdoc-rules-require-param-description-options-29"></a>
 #### Options
 
+<a name="user-content-eslint-plugin-jsdoc-rules-require-param-description-options-29-setdefaultdestructuredrootdescription"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-description-options-29-setdefaultdestructuredrootdescription"></a>
+##### <code>setDefaultDestructuredRootDescription</code>
+
+Whether to set a default destructured root description. For example, you may
+wish to avoid manually having to set the description for a `@param`
+corresponding to a destructured root object as it should always be the same
+type of object. Uses `defaultDestructuredRootDescription` for the description
+string. Defaults to `false`.
+
+<a name="user-content-eslint-plugin-jsdoc-rules-require-param-description-options-29-defaultdestructuredrootdescription"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-description-options-29-defaultdestructuredrootdescription"></a>
+##### <code>defaultDestructuredRootDescription</code>
+
+The description string to set by default for destructured roots. Defaults to
+"The root object".
+
 <a name="user-content-eslint-plugin-jsdoc-rules-require-param-description-options-29-contexts-8"></a>
 <a name="eslint-plugin-jsdoc-rules-require-param-description-options-29-contexts-8"></a>
 ##### <code>contexts</code>
@@ -14796,7 +14819,8 @@ section of our README for more on the expected format.
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 |Recommended|true|
-|Options|`contexts`|
+|Options|`setDefaultDestructuredRootDescription`, `defaultDestructuredRootDescription`, `contexts`|
+|Settings|`exemptDestructuredRootsFromChecks`|
 
 The following patterns are considered problems:
 
@@ -14849,6 +14873,48 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
 // Message: Unexpected tag `@param`
+
+/**
+ * @param foo
+ */
+function quux (foo) {
+
+}
+// "jsdoc/require-param-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag:not([name=props]))","context":"FunctionDeclaration"}]}]
+// Message: Missing JSDoc @param "foo" description.
+
+/**
+ * @param {number} foo Foo description
+ * @param {object} root
+ * @param {boolean} baz Baz description
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// "jsdoc/require-param-description": ["error"|"warn", {"setDefaultDestructuredRootDescription":true}]
+// Message: Missing root description for @param.
+
+/**
+ * @param {number} foo Foo description
+ * @param {object} root
+ * @param {boolean} baz Baz description
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// "jsdoc/require-param-description": ["error"|"warn", {"defaultDestructuredRootDescription":"Root description","setDefaultDestructuredRootDescription":true}]
+// Message: Missing root description for @param.
+
+/**
+ * @param {number} foo Foo description
+ * @param {object} root
+ * @param {boolean} baz Baz description
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// "jsdoc/require-param-description": ["error"|"warn", {"setDefaultDestructuredRootDescription":false}]
+// Message: Missing JSDoc @param "root" description.
 ````
 
 The following patterns are not considered problems:
@@ -14885,6 +14951,34 @@ function quux (foo) {
  * @callback
  * @param foo
  */
+
+/**
+ * @param props
+ */
+function quux (props) {
+
+}
+// "jsdoc/require-param-description": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag:not([name=props]))","context":"FunctionDeclaration"}]}]
+
+/**
+ * @param {number} foo Foo description
+ * @param {object} root
+ * @param {boolean} baz Baz description
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// Settings: {"jsdoc":{"exemptDestructuredRootsFromChecks":true}}
+
+/**
+ * @param {number} foo Foo description
+ * @param {object} root
+ * @param {object} root.bar
+ */
+function quux (foo, {bar: {baz}}) {
+
+}
+// Settings: {"jsdoc":{"exemptDestructuredRootsFromChecks":true}}
 ````
 
 
@@ -15037,10 +15131,31 @@ function example(cb) {
 
 Requires that each `@param` tag has a `type` value.
 
+Will exempt destructured roots and their children if
+`settings.exemptDestructuredRootsFromChecks` is set to `true` (e.g.,
+`@param props` will be exempted from requiring a type given
+`function someFunc ({child1, child2})`).
+
 <a name="user-content-eslint-plugin-jsdoc-rules-require-param-type-options-31"></a>
 <a name="eslint-plugin-jsdoc-rules-require-param-type-options-31"></a>
 #### Options
 
+<a name="user-content-eslint-plugin-jsdoc-rules-require-param-type-options-31-setdefaultdestructuredroottype"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-type-options-31-setdefaultdestructuredroottype"></a>
+##### <code>setDefaultDestructuredRootType</code>
+
+Whether to set a default destructured root type. For example, you may wish
+to avoid manually having to set the type for a `@param`
+corresponding to a destructured root object as it is always going to be an
+object. Uses `defaultDestructuredRootType` for the type string. Defaults to
+`false`.
+
+<a name="user-content-eslint-plugin-jsdoc-rules-require-param-type-options-31-defaultdestructuredroottype"></a>
+<a name="eslint-plugin-jsdoc-rules-require-param-type-options-31-defaultdestructuredroottype"></a>
+##### <code>defaultDestructuredRootType</code>
+
+The type string to set by default for destructured roots. Defaults to "object".
+
 <a name="user-content-eslint-plugin-jsdoc-rules-require-param-type-options-31-contexts-10"></a>
 <a name="eslint-plugin-jsdoc-rules-require-param-type-options-31-contexts-10"></a>
 ##### <code>contexts</code>
@@ -15062,7 +15177,8 @@ section of our README for more on the expected format.
 |Tags|`param`|
 |Aliases|`arg`, `argument`|
 |Recommended|true|
-|Options|`contexts`|
+|Options|`setDefaultDestructuredRootType`, `defaultDestructuredRootType`, `contexts`|
+|Settings|`exemptDestructuredRootsFromChecks`|
 
 The following patterns are considered problems:
 
@@ -15122,6 +15238,39 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
 // Message: Unexpected tag `@param`
+
+/**
+ * @param {number} foo
+ * @param root
+ * @param {boolean} baz
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// "jsdoc/require-param-type": ["error"|"warn", {"setDefaultDestructuredRootType":true}]
+// Message: Missing root type for @param.
+
+/**
+ * @param {number} foo
+ * @param root
+ * @param {boolean} baz
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// "jsdoc/require-param-type": ["error"|"warn", {"defaultDestructuredRootType":"Object","setDefaultDestructuredRootType":true}]
+// Message: Missing root type for @param.
+
+/**
+ * @param {number} foo
+ * @param root
+ * @param {boolean} baz
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// "jsdoc/require-param-type": ["error"|"warn", {"setDefaultDestructuredRootType":false}]
+// Message: Missing JSDoc @param "root" type.
 ````
 
 The following patterns are not considered problems:
@@ -15158,6 +15307,26 @@ function quux (foo) {
  * @callback
  * @param foo
  */
+
+/**
+ * @param {number} foo
+ * @param root
+ * @param {boolean} baz
+ */
+function quux (foo, {bar}, baz) {
+
+}
+// Settings: {"jsdoc":{"exemptDestructuredRootsFromChecks":true}}
+
+/**
+ * @param {number} foo
+ * @param root
+ * @param root.bar
+ */
+function quux (foo, {bar: {baz}}) {
+
+}
+// Settings: {"jsdoc":{"exemptDestructuredRootsFromChecks":true}}
 ````
 
 
@@ -15192,7 +15361,7 @@ function quux ({foo: bar, baz: bax = 5}) {
 }
 ```
 
-..the fixed jsdoc will be:
+...the fixed jsdoc will be:
 
 ```js
 /**

src/iterateJsdoc.js

@@ -818,6 +818,9 @@ const getSettings = (context) => {
     implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,
     augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,
 
+    // `require-param-type`, `require-param-description`
+    exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,
+
     // Many rules, e.g., `check-tag-names`
     mode: context.settings.jsdoc?.mode ??
       (context.parserPath.includes('@typescript-eslint') ? 'typescript' : 'jsdoc'),