eslint-plugin-jsdoc 46.4.6 → 46.5.0

package/docs/rules/no-bad-blocks.md

@@ -1,174 +0,0 @@
-<a name="user-content-no-bad-blocks"></a>
-<a name="no-bad-blocks"></a>
-### <code>no-bad-blocks</code>
-
-
-
-This rule checks for multi-line-style comments which fail to meet the
-criteria of a jsdoc block, namely that it should begin with two and only two
-asterisks, but which appear to be intended as jsdoc blocks due to the presence
-of whitespace followed by whitespace or asterisks, and
-an at-sign (`@`) and some non-whitespace (as with a jsdoc block tag).
-
-<a name="user-content-fixer"></a>
-<a name="fixer"></a>
-## Fixer
-
-(TODO)
-
-<a name="user-content-options"></a>
-<a name="options"></a>
-## Options
-
-Takes an optional options object with the following.
-
-<a name="user-content-options-ignore"></a>
-<a name="options-ignore"></a>
-### <code>ignore</code>
-
-An array of directives that will not be reported if present at the beginning of
-a multi-comment block and at-sign `/* @`.
-
-Defaults to `['ts-check', 'ts-expect-error', 'ts-ignore', 'ts-nocheck']`
-(some directives [used by TypeScript](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check)).
-
-<a name="user-content-options-preventallmultiasteriskblocks"></a>
-<a name="options-preventallmultiasteriskblocks"></a>
-### <code>preventAllMultiAsteriskBlocks</code>
-
-A boolean (defaulting to `false`) which if `true` will prevent all
-JSDoc-like blocks with more than two initial asterisks even those without
-apparent tag content.
-
-<a name="user-content-context-and-settings"></a>
-<a name="context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|Everywhere|
-|Tags|N/A|
-|Recommended|false|
-|Options|`ignore`, `preventAllMultiAsteriskBlocks`|
-
-<a name="user-content-failing-examples"></a>
-<a name="failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/*
- * @param foo
- */
-function quux (foo) {
-
-}
-// Message: Expected JSDoc-like comment to begin with two asterisks.
-
-/*
- * @property foo
- */
-// Message: Expected JSDoc-like comment to begin with two asterisks.
-
-function quux() {
-
-}
-// Settings: {"jsdoc":{"structuredTags":{"see":{"name":false,"required":["name"]}}}}
-// Message: Cannot add "name" to `require` with the tag's `name` set to `false`
-
-/* @ts-ignore */
-// "jsdoc/no-bad-blocks": ["error"|"warn", {"ignore":[]}]
-// Message: Expected JSDoc-like comment to begin with two asterisks.
-
-/*
- * Some description.
- *
- * @returns {string} Some string
- */
-function echo() {
-  return 'Something';
-}
-// Message: Expected JSDoc-like comment to begin with two asterisks.
-
-/***
- * @param foo
- */
-function quux (foo) {
-
-}
-// Message: Expected JSDoc-like comment to begin with two asterisks.
-
-/***
- *
- */
-function quux (foo) {
-
-}
-// "jsdoc/no-bad-blocks": ["error"|"warn", {"preventAllMultiAsteriskBlocks":true}]
-// Message: Expected JSDoc-like comment to begin with two asterisks.
-````
-
-
-
-<a name="user-content-passing-examples"></a>
-<a name="passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * @property foo
- */
-
-/**
- * @param foo
- */
- function quux () {
-
- }
-
-function quux () {
-
-}
-
-/* This could just be intended as a regular multiline comment,
-   so don't report this */
-function quux () {
-
-}
-
-/* Just a regular multiline comment with an `@` but not appearing
-    like a tag in a jsdoc-block, so don't report */
-function quux () {
-
-}
-
-/* @ts-check */
-
-/* @ts-expect-error */
-
-/* @ts-ignore */
-
-/* @ts-nocheck */
-
-/* */
-
-/** */
-
-/* @custom */
-// "jsdoc/no-bad-blocks": ["error"|"warn", {"ignore":["custom"]}]
-
-/***
- * This is not JSDoc because of the 3 asterisks, but
- * is allowed without `preventAllMultiAsteriskBlocks`, as
- * some might wish normal multiline comments.
- */
-function quux (foo) {
-
-}
-
-/***/
-````
-

package/docs/rules/no-blank-block-descriptions.md

@@ -1,91 +0,0 @@
-<a name="user-content-no-blank-block-descriptions"></a>
-<a name="no-blank-block-descriptions"></a>
-### <code>no-blank-block-descriptions</code>
-
-
-
-If tags are present, this rule will prevent empty lines in the
-block description.
-
-If no tags are present, this rule will prevent extra empty lines
-in the block description.
-
-<a name="user-content-fixer"></a>
-<a name="fixer"></a>
-## Fixer
-
-(TODO)
-
-<a name="user-content-context-and-settings"></a>
-<a name="context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|everywhere|
-|Tags|(Block description)|
-|Recommended|false|
-|Settings||
-|Options||
-
-<a name="user-content-failing-examples"></a>
-<a name="failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- *
- * @param {number} x
- */
-function functionWithClearName(x) {}
-// Message: There should be no blank lines in block descriptions followed by tags.
-
-/**
- *
- *
- */
-function functionWithClearName() {}
-// Message: There should be no extra blank lines in block descriptions not followed by tags.
-````
-
-
-
-<a name="user-content-passing-examples"></a>
-<a name="passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * Non-empty description
- * @param {number} x
- */
-function functionWithClearName(x) {}
-
-/**
- * @param {number} x
- */
-function functionWithClearName(x) {}
-
-/**
- *
- */
-function functionWithClearName() {}
-
-/**
- */
-function functionWithClearName() {}
-
-/** */
-function functionWithClearName() {}
-
-/** Some desc. */
-function functionWithClearName() {}
-
-/** @someTag */
-function functionWithClearName() {}
-````
-

package/docs/rules/no-blank-blocks.md

@@ -1,98 +0,0 @@
-<a name="user-content-no-blank-blocks"></a>
-<a name="no-blank-blocks"></a>
-# <code>no-blank-blocks</code>
-
-* [Fixer](#user-content-no-blank-blocks-fixer)
-* [Failing examples](#user-content-no-blank-blocks-failing-examples)
-* [Passing examples](#user-content-no-blank-blocks-passing-examples)
-
-
-Reports and optionally removes blocks with whitespace only.
-
-<a name="user-content-no-blank-blocks-fixer"></a>
-<a name="no-blank-blocks-fixer"></a>
-## Fixer
-
-(TODO)
-
-<a name="user-content-no-blank-blocks-fixer-options"></a>
-<a name="no-blank-blocks-fixer-options"></a>
-#### Options
-
-<a name="user-content-no-blank-blocks-fixer-options-enablefixer"></a>
-<a name="no-blank-blocks-fixer-options-enablefixer"></a>
-##### <code>enableFixer</code>
-
-Whether or not to auto-remove the blank block. Defaults to `false`.
-
-|||
-|---|---|
-|Context|everywhere|
-|Tags|N/A|
-|Recommended|false|
-|Settings||
-|Options|`enableFixer`|
-
-<a name="user-content-no-blank-blocks-failing-examples"></a>
-<a name="no-blank-blocks-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/** */
-// "jsdoc/no-blank-blocks": ["error"|"warn", {"enableFixer":true}]
-// Message: No empty blocks
-
-/**
- */
-// "jsdoc/no-blank-blocks": ["error"|"warn", {"enableFixer":true}]
-// Message: No empty blocks
-
-/**
- *
- */
-// "jsdoc/no-blank-blocks": ["error"|"warn", {"enableFixer":true}]
-// Message: No empty blocks
-
-/**
- *
- *
- */
-// "jsdoc/no-blank-blocks": ["error"|"warn", {"enableFixer":true}]
-// Message: No empty blocks
-
-/**
- *
- *
- */
-// "jsdoc/no-blank-blocks": ["error"|"warn", {"enableFixer":false}]
-// Message: No empty blocks
-
-/**
- *
- *
- */
-// Message: No empty blocks
-````
-
-
-
-<a name="user-content-no-blank-blocks-passing-examples"></a>
-<a name="no-blank-blocks-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/** @tag */
-
-/**
- * Text
- */
-
-/**
- * @tag
- */
-````
-

package/docs/rules/no-defaults.md

@@ -1,207 +0,0 @@
-<a name="user-content-no-defaults"></a>
-<a name="no-defaults"></a>
-# <code>no-defaults</code>
-
-* [Fixer](#user-content-no-defaults-fixer)
-* [Options](#user-content-no-defaults-options)
-    * [`noOptionalParamNames`](#user-content-no-defaults-options-nooptionalparamnames)
-    * [`contexts`](#user-content-no-defaults-options-contexts)
-* [Context and settings](#user-content-no-defaults-context-and-settings)
-* [Failing examples](#user-content-no-defaults-failing-examples)
-* [Passing examples](#user-content-no-defaults-passing-examples)
-
-
-This rule reports defaults being used on the relevant portion of `@param`
-or `@default`. It also optionally reports the presence of the
-square-bracketed optional arguments at all.
-
-The rule is intended to prevent the indication of defaults on tags where
-this would be redundant with ES6 default parameters (or for `@default`,
-where it would be redundant with the context to which the `@default`
-tag is attached).
-
-Unless your `@default` is on a function, you will need to set `contexts`
-to an appropriate context, including, if you wish, "any".
-
-<a name="user-content-no-defaults-fixer"></a>
-<a name="no-defaults-fixer"></a>
-## Fixer
-
-(TODO)
-
-<a name="user-content-no-defaults-options"></a>
-<a name="no-defaults-options"></a>
-## Options
-
-<a name="user-content-no-defaults-options-nooptionalparamnames"></a>
-<a name="no-defaults-options-nooptionalparamnames"></a>
-### <code>noOptionalParamNames</code>
-
-Set this to `true` to report the presence of optional parameters. May be
-used if the project is insisting on optionality being indicated by
-the presence of ES6 default parameters (bearing in mind that such
-"defaults" are only applied when the supplied value is missing or
-`undefined` but not for `null` or other "falsey" values).
-
-<a name="user-content-no-defaults-options-contexts"></a>
-<a name="no-defaults-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-no-defaults-context-and-settings"></a>
-<a name="no-defaults-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|`param`, `default`|
-|Aliases|`arg`, `argument`, `defaultvalue`|
-|Recommended|false|
-|Options|`contexts`, `noOptionalParamNames`|
-
-<a name="user-content-no-defaults-failing-examples"></a>
-<a name="no-defaults-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- * @param {number} [foo="7"]
- */
-function quux (foo) {
-
-}
-// Message: Defaults are not permitted on @param.
-
-class Test {
-    /**
-     * @param {number} [foo="7"]
-     */
-    quux (foo) {
-
-    }
-}
-// Message: Defaults are not permitted on @param.
-
-/**
- * @param {number} [foo="7"]
- */
-function quux (foo) {
-
-}
-// "jsdoc/no-defaults": ["error"|"warn", {"noOptionalParamNames":true}]
-// Message: Optional param names are not permitted on @param.
-
-/**
- * @arg {number} [foo="7"]
- */
-function quux (foo) {
-
-}
-// Settings: {"jsdoc":{"tagNamePreference":{"param":"arg"}}}
-// Message: Defaults are not permitted on @arg.
-
-/**
- * @param {number} [foo="7"]
- */
-function quux (foo) {
-
-}
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-// Message: Defaults are not permitted on @param.
-
-/**
- * @function
- * @param {number} [foo="7"]
- */
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-// Message: Defaults are not permitted on @param.
-
-/**
- * @callback
- * @param {number} [foo="7"]
- */
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-// Message: Defaults are not permitted on @param.
-
-/**
- * @default {}
- */
-const a = {};
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-// Message: Default values are not permitted on @default.
-
-/**
- * @defaultvalue {}
- */
-const a = {};
-// Settings: {"jsdoc":{"tagNamePreference":{"default":"defaultvalue"}}}
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-// Message: Default values are not permitted on @defaultvalue.
-````
-
-
-
-<a name="user-content-no-defaults-passing-examples"></a>
-<a name="no-defaults-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * @param foo
- */
-function quux (foo) {
-
-}
-
-/**
- * @param {number} foo
- */
-function quux (foo) {
-
-}
-
-/**
- * @param foo
- */
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-
-/**
- * @function
- * @param {number} foo
- */
-
-/**
- * @callback
- * @param {number} foo
- */
-
-/**
- * @param {number} foo
- */
-function quux (foo) {
-
-}
-// "jsdoc/no-defaults": ["error"|"warn", {"noOptionalParamNames":true}]
-
-/**
- * @default
- */
-const a = {};
-// "jsdoc/no-defaults": ["error"|"warn", {"contexts":["any"]}]
-````
-