eslint-plugin-jsdoc 46.4.5 → 46.5.0

package/docs/rules/require-param-description.md

@@ -1,238 +0,0 @@
-<a name="user-content-require-param-description"></a>
-<a name="require-param-description"></a>
-# <code>require-param-description</code>
-
-* [Options](#user-content-require-param-description-options)
-    * [`setDefaultDestructuredRootDescription`](#user-content-require-param-description-options-setdefaultdestructuredrootdescription)
-    * [`defaultDestructuredRootDescription`](#user-content-require-param-description-options-defaultdestructuredrootdescription)
-    * [`contexts`](#user-content-require-param-description-options-contexts)
-* [Context and settings](#user-content-require-param-description-context-and-settings)
-* [Failing examples](#user-content-require-param-description-failing-examples)
-* [Passing examples](#user-content-require-param-description-passing-examples)
-
-
-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-require-param-description-options"></a>
-<a name="require-param-description-options"></a>
-## Options
-
-<a name="user-content-require-param-description-options-setdefaultdestructuredrootdescription"></a>
-<a name="require-param-description-options-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-require-param-description-options-defaultdestructuredrootdescription"></a>
-<a name="require-param-description-options-defaultdestructuredrootdescription"></a>
-### <code>defaultDestructuredRootDescription</code>
-
-The description string to set by default for destructured roots. Defaults to
-"The root object".
-
-<a name="user-content-require-param-description-options-contexts"></a>
-<a name="require-param-description-options-contexts"></a>
-### <code>contexts</code>
-
-Set this to an array of strings representing the AST context (or an object with
-`context` and `comment` properties) where you wish the rule to be applied.
-Overrides the default contexts (see below). Set to `"any"` if you want
-the rule to apply to any jsdoc block throughout your files (as is necessary
-for finding function blocks not attached to a function declaration or
-expression, i.e., `@callback` or `@function` (or its aliases `@func` or
-`@method`) (including those associated with an `@interface`).
-
-See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
-section of our README for more on the expected format.
-
-<a name="user-content-require-param-description-context-and-settings"></a>
-<a name="require-param-description-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|`param`|
-|Aliases|`arg`, `argument`|
-|Recommended|true|
-|Options|`contexts`, `defaultDestructuredRootDescription`, `setDefaultDestructuredRootDescription`|
-|Settings|`exemptDestructuredRootsFromChecks`|
-
-<a name="user-content-require-param-description-failing-examples"></a>
-<a name="require-param-description-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-// Message: Missing JSDoc @param "foo" description.
-
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-// "jsdoc/require-param-description": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @param "foo" description.
-
-/**
- * @function
- * @param foo
- */
-// "jsdoc/require-param-description": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @param "foo" description.
-
-/**
- * @callback
- * @param foo
- */
-// "jsdoc/require-param-description": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @param "foo" description.
-
-/**
- * @arg foo
- */
-function quux (foo) {
-
-}
-// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
-// Message: Missing JSDoc @arg "foo" description.
-
-/**
- * @param foo
- */
-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.
-````
-
-
-
-<a name="user-content-require-param-description-passing-examples"></a>
-<a name="require-param-description-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- *
- */
-function quux (foo) {
-
-}
-
-/**
- * @param foo Foo.
- */
-function quux (foo) {
-
-}
-
-/**
- * @param foo Foo.
- */
-function quux (foo) {
-
-}
-// "jsdoc/require-param-description": ["error"|"warn", {"contexts":["any"]}]
-
-/**
- * @function
- * @param 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}}
-````
-

package/docs/rules/require-param-name.md

@@ -1,163 +0,0 @@
-<a name="user-content-require-param-name"></a>
-<a name="require-param-name"></a>
-# <code>require-param-name</code>
-
-* [Options](#user-content-require-param-name-options)
-    * [`contexts`](#user-content-require-param-name-options-contexts)
-* [Context and settings](#user-content-require-param-name-context-and-settings)
-* [Failing examples](#user-content-require-param-name-failing-examples)
-* [Passing examples](#user-content-require-param-name-passing-examples)
-
-
-Requires that all `@param` tags have names.
-
-> The `@param` tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.
->
-> [JSDoc](https://jsdoc.app/tags-param.html#overview)
-
-<a name="user-content-require-param-name-options"></a>
-<a name="require-param-name-options"></a>
-## Options
-
-<a name="user-content-require-param-name-options-contexts"></a>
-<a name="require-param-name-options-contexts"></a>
-### <code>contexts</code>
-
-Set this to an array of strings representing the AST context (or an object with
-`context` and `comment` properties) where you wish the rule to be applied.
-Overrides the default contexts (see below). Set to `"any"` if you want
-the rule to apply to any jsdoc block throughout your files (as is necessary
-for finding function blocks not attached to a function declaration or
-expression, i.e., `@callback` or `@function` (or its aliases `@func` or
-`@method`) (including those associated with an `@interface`).
-
-See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
-section of our README for more on the expected format.
-
-<a name="user-content-require-param-name-context-and-settings"></a>
-<a name="require-param-name-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|`param`|
-|Aliases|`arg`, `argument`|
-|Recommended|true|
-|Options|`contexts`|
-
-<a name="user-content-require-param-name-failing-examples"></a>
-<a name="require-param-name-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- * @param
- */
-function quux (foo) {
-
-}
-// Message: There must be an identifier after @param type.
-
-/**
- * @param {string}
- */
-function quux (foo) {
-
-}
-// Message: There must be an identifier after @param tag.
-
-/**
- * @param {string}
- */
-function quux (foo) {
-
-}
-// "jsdoc/require-param-name": ["error"|"warn", {"contexts":["any"]}]
-// Message: There must be an identifier after @param tag.
-
-/**
- * @function
- * @param {string}
- */
-// "jsdoc/require-param-name": ["error"|"warn", {"contexts":["any"]}]
-// Message: There must be an identifier after @param tag.
-
-/**
- * @callback
- * @param {string}
- */
-// "jsdoc/require-param-name": ["error"|"warn", {"contexts":["any"]}]
-// Message: There must be an identifier after @param tag.
-
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-// Settings: {"jsdoc":{"tagNamePreference":{"param":false}}}
-// Message: Unexpected tag `@param`
-````
-
-
-
-<a name="user-content-require-param-name-passing-examples"></a>
-<a name="require-param-name-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-// "jsdoc/require-param-name": ["error"|"warn", {"contexts":["any"]}]
-
-/**
- * @param {string} foo
- */
-function quux (foo) {
-
-}
-
-/**
- * @function
- * @param
- */
-
-/**
- * @callback
- * @param
- */
-
-/**
- * @param {Function} [processor=data => data] A function to run
- */
-function processData(processor) {
-  return processor(data)
-}
-
-/** Example with multi-line param type.
-*
-* @param {function(
-*   number
-* )} cb Callback.
-*/
-function example(cb) {
-  cb(42);
-}
-````
-

package/docs/rules/require-param-type.md

@@ -1,227 +0,0 @@
-<a name="user-content-require-param-type"></a>
-<a name="require-param-type"></a>
-# <code>require-param-type</code>
-
-* [Options](#user-content-require-param-type-options)
-    * [`setDefaultDestructuredRootType`](#user-content-require-param-type-options-setdefaultdestructuredroottype)
-    * [`defaultDestructuredRootType`](#user-content-require-param-type-options-defaultdestructuredroottype)
-    * [`contexts`](#user-content-require-param-type-options-contexts)
-* [Context and settings](#user-content-require-param-type-context-and-settings)
-* [Failing examples](#user-content-require-param-type-failing-examples)
-* [Passing examples](#user-content-require-param-type-passing-examples)
-
-
-Requires that each `@param` tag has a `type` value (within curly brackets).
-
-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-require-param-type-options"></a>
-<a name="require-param-type-options"></a>
-## Options
-
-<a name="user-content-require-param-type-options-setdefaultdestructuredroottype"></a>
-<a name="require-param-type-options-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-require-param-type-options-defaultdestructuredroottype"></a>
-<a name="require-param-type-options-defaultdestructuredroottype"></a>
-### <code>defaultDestructuredRootType</code>
-
-The type string to set by default for destructured roots. Defaults to "object".
-
-<a name="user-content-require-param-type-options-contexts"></a>
-<a name="require-param-type-options-contexts"></a>
-### <code>contexts</code>
-
-Set this to an array of strings representing the AST context (or an object with
-`context` and `comment` properties) where you wish the rule to be applied.
-Overrides the default contexts (see below). Set to `"any"` if you want
-the rule to apply to any jsdoc block throughout your files (as is necessary
-for finding function blocks not attached to a function declaration or
-expression, i.e., `@callback` or `@function` (or its aliases `@func` or
-`@method`) (including those associated with an `@interface`).
-
-See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
-section of our README for more on the expected format.
-
-<a name="user-content-require-param-type-context-and-settings"></a>
-<a name="require-param-type-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|`param`|
-|Aliases|`arg`, `argument`|
-|Recommended|true|
-|Options|`contexts`, `defaultDestructuredRootType`, `setDefaultDestructuredRootType`|
-|Settings|`exemptDestructuredRootsFromChecks`|
-
-<a name="user-content-require-param-type-failing-examples"></a>
-<a name="require-param-type-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-// Message: Missing JSDoc @param "foo" type.
-
-/**
- * @param {a xxx
- */
-function quux () {
-}
-// Message: Missing JSDoc @param "" type.
-
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-// "jsdoc/require-param-type": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @param "foo" type.
-
-/**
- * @function
- * @param foo
- */
-// "jsdoc/require-param-type": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @param "foo" type.
-
-/**
- * @callback
- * @param foo
- */
-// "jsdoc/require-param-type": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @param "foo" type.
-
-/**
- * @arg foo
- */
-function quux (foo) {
-
-}
-// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
-// Message: Missing JSDoc @arg "foo" type.
-
-/**
- * @param foo
- */
-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.
-````
-
-
-
-<a name="user-content-require-param-type-passing-examples"></a>
-<a name="require-param-type-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- *
- */
-function quux (foo) {
-
-}
-
-/**
- * @param {number} foo
- */
-function quux (foo) {
-
-}
-
-/**
- * @param {number} foo
- */
-function quux (foo) {
-
-}
-// "jsdoc/require-param-type": ["error"|"warn", {"contexts":["any"]}]
-
-/**
- * @function
- * @param 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}}
-````
-