diff --git a/README.md b/README.md
index 03038d123..57cd0500f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+
# eslint-plugin-jsdoc
@@ -9,72 +10,73 @@
JSDoc linting rules for ESLint.
-* [eslint-plugin-jsdoc](#eslint-plugin-jsdoc)
- * [Installation](#eslint-plugin-jsdoc-installation)
- * [Configuration](#eslint-plugin-jsdoc-configuration)
- * [Options](#eslint-plugin-jsdoc-options)
- * [Settings](#eslint-plugin-jsdoc-settings)
- * [Allow tags (`@private` or `@internal`) to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block)
- * [`maxLines` and `minLines`](#eslint-plugin-jsdoc-settings-maxlines-and-minlines)
- * [Mode](#eslint-plugin-jsdoc-settings-mode)
- * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
- * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields)
- * [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
- * [`structuredTags`](#eslint-plugin-jsdoc-settings-structuredtags)
- * [Advanced](#eslint-plugin-jsdoc-advanced)
- * [AST and Selectors](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
- * [Rules](#eslint-plugin-jsdoc-rules)
- * [`check-access`](#eslint-plugin-jsdoc-rules-check-access)
- * [`check-alignment`](#eslint-plugin-jsdoc-rules-check-alignment)
- * [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples)
- * [`check-indentation`](#eslint-plugin-jsdoc-rules-check-indentation)
- * [`check-line-alignment`](#eslint-plugin-jsdoc-rules-check-line-alignment)
- * [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
- * [`check-property-names`](#eslint-plugin-jsdoc-rules-check-property-names)
- * [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax)
- * [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names)
- * [`check-types`](#eslint-plugin-jsdoc-rules-check-types)
- * [`check-values`](#eslint-plugin-jsdoc-rules-check-values)
- * [`empty-tags`](#eslint-plugin-jsdoc-rules-empty-tags)
- * [`implements-on-classes`](#eslint-plugin-jsdoc-rules-implements-on-classes)
- * [`match-description`](#eslint-plugin-jsdoc-rules-match-description)
- * [`match-name`](#eslint-plugin-jsdoc-rules-match-name)
- * [`multiline-blocks`](#eslint-plugin-jsdoc-rules-multiline-blocks)
- * [`newline-after-description`](#eslint-plugin-jsdoc-rules-newline-after-description)
- * [`no-bad-blocks`](#eslint-plugin-jsdoc-rules-no-bad-blocks)
- * [`no-defaults`](#eslint-plugin-jsdoc-rules-no-defaults)
- * [`no-missing-syntax`](#eslint-plugin-jsdoc-rules-no-missing-syntax)
- * [`no-multi-asterisks`](#eslint-plugin-jsdoc-rules-no-multi-asterisks)
- * [`no-restricted-syntax`](#eslint-plugin-jsdoc-rules-no-restricted-syntax)
- * [`no-types`](#eslint-plugin-jsdoc-rules-no-types)
- * [`no-undefined-types`](#eslint-plugin-jsdoc-rules-no-undefined-types)
- * [`require-asterisk-prefix`](#eslint-plugin-jsdoc-rules-require-asterisk-prefix)
- * [`require-description-complete-sentence`](#eslint-plugin-jsdoc-rules-require-description-complete-sentence)
- * [`require-description`](#eslint-plugin-jsdoc-rules-require-description)
- * [`require-example`](#eslint-plugin-jsdoc-rules-require-example)
- * [`require-file-overview`](#eslint-plugin-jsdoc-rules-require-file-overview)
- * [`require-hyphen-before-param-description`](#eslint-plugin-jsdoc-rules-require-hyphen-before-param-description)
- * [`require-jsdoc`](#eslint-plugin-jsdoc-rules-require-jsdoc)
- * [`require-param-description`](#eslint-plugin-jsdoc-rules-require-param-description)
- * [`require-param-name`](#eslint-plugin-jsdoc-rules-require-param-name)
- * [`require-param-type`](#eslint-plugin-jsdoc-rules-require-param-type)
- * [`require-param`](#eslint-plugin-jsdoc-rules-require-param)
- * [`require-property`](#eslint-plugin-jsdoc-rules-require-property)
- * [`require-property-description`](#eslint-plugin-jsdoc-rules-require-property-description)
- * [`require-property-name`](#eslint-plugin-jsdoc-rules-require-property-name)
- * [`require-property-type`](#eslint-plugin-jsdoc-rules-require-property-type)
- * [`require-returns-check`](#eslint-plugin-jsdoc-rules-require-returns-check)
- * [`require-returns-description`](#eslint-plugin-jsdoc-rules-require-returns-description)
- * [`require-returns-type`](#eslint-plugin-jsdoc-rules-require-returns-type)
- * [`require-returns`](#eslint-plugin-jsdoc-rules-require-returns)
- * [`require-throws`](#eslint-plugin-jsdoc-rules-require-throws)
- * [`require-yields`](#eslint-plugin-jsdoc-rules-require-yields)
- * [`require-yields-check`](#eslint-plugin-jsdoc-rules-require-yields-check)
- * [`sort-tags`](#eslint-plugin-jsdoc-rules-sort-tags)
- * [`tag-lines`](#eslint-plugin-jsdoc-rules-tag-lines)
- * [`valid-types`](#eslint-plugin-jsdoc-rules-valid-types)
-
-
+* [eslint-plugin-jsdoc](#user-content-eslint-plugin-jsdoc)
+ * [Installation](#user-content-eslint-plugin-jsdoc-installation)
+ * [Configuration](#user-content-eslint-plugin-jsdoc-configuration)
+ * [Options](#user-content-eslint-plugin-jsdoc-options)
+ * [Settings](#user-content-eslint-plugin-jsdoc-settings)
+ * [Allow tags (`@private` or `@internal`) to disable rules for that comment block](#user-content-eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block)
+ * [`maxLines` and `minLines`](#user-content-eslint-plugin-jsdoc-settings-maxlines-and-minlines)
+ * [Mode](#user-content-eslint-plugin-jsdoc-settings-mode)
+ * [Alias Preference](#user-content-eslint-plugin-jsdoc-settings-alias-preference)
+ * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#user-content-eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields)
+ * [Settings to Configure `check-types` and `no-undefined-types`](#user-content-eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
+ * [`structuredTags`](#user-content-eslint-plugin-jsdoc-settings-structuredtags)
+ * [Advanced](#user-content-eslint-plugin-jsdoc-advanced)
+ * [AST and Selectors](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
+ * [Rules](#user-content-eslint-plugin-jsdoc-rules)
+ * [`check-access`](#user-content-eslint-plugin-jsdoc-rules-check-access)
+ * [`check-alignment`](#user-content-eslint-plugin-jsdoc-rules-check-alignment)
+ * [`check-examples`](#user-content-eslint-plugin-jsdoc-rules-check-examples)
+ * [`check-indentation`](#user-content-eslint-plugin-jsdoc-rules-check-indentation)
+ * [`check-line-alignment`](#user-content-eslint-plugin-jsdoc-rules-check-line-alignment)
+ * [`check-param-names`](#user-content-eslint-plugin-jsdoc-rules-check-param-names)
+ * [`check-property-names`](#user-content-eslint-plugin-jsdoc-rules-check-property-names)
+ * [`check-syntax`](#user-content-eslint-plugin-jsdoc-rules-check-syntax)
+ * [`check-tag-names`](#user-content-eslint-plugin-jsdoc-rules-check-tag-names)
+ * [`check-types`](#user-content-eslint-plugin-jsdoc-rules-check-types)
+ * [`check-values`](#user-content-eslint-plugin-jsdoc-rules-check-values)
+ * [`empty-tags`](#user-content-eslint-plugin-jsdoc-rules-empty-tags)
+ * [`implements-on-classes`](#user-content-eslint-plugin-jsdoc-rules-implements-on-classes)
+ * [`match-description`](#user-content-eslint-plugin-jsdoc-rules-match-description)
+ * [`match-name`](#user-content-eslint-plugin-jsdoc-rules-match-name)
+ * [`multiline-blocks`](#user-content-eslint-plugin-jsdoc-rules-multiline-blocks)
+ * [`newline-after-description`](#user-content-eslint-plugin-jsdoc-rules-newline-after-description)
+ * [`no-bad-blocks`](#user-content-eslint-plugin-jsdoc-rules-no-bad-blocks)
+ * [`no-defaults`](#user-content-eslint-plugin-jsdoc-rules-no-defaults)
+ * [`no-missing-syntax`](#user-content-eslint-plugin-jsdoc-rules-no-missing-syntax)
+ * [`no-multi-asterisks`](#user-content-eslint-plugin-jsdoc-rules-no-multi-asterisks)
+ * [`no-restricted-syntax`](#user-content-eslint-plugin-jsdoc-rules-no-restricted-syntax)
+ * [`no-types`](#user-content-eslint-plugin-jsdoc-rules-no-types)
+ * [`no-undefined-types`](#user-content-eslint-plugin-jsdoc-rules-no-undefined-types)
+ * [`require-asterisk-prefix`](#user-content-eslint-plugin-jsdoc-rules-require-asterisk-prefix)
+ * [`require-description-complete-sentence`](#user-content-eslint-plugin-jsdoc-rules-require-description-complete-sentence)
+ * [`require-description`](#user-content-eslint-plugin-jsdoc-rules-require-description)
+ * [`require-example`](#user-content-eslint-plugin-jsdoc-rules-require-example)
+ * [`require-file-overview`](#user-content-eslint-plugin-jsdoc-rules-require-file-overview)
+ * [`require-hyphen-before-param-description`](#user-content-eslint-plugin-jsdoc-rules-require-hyphen-before-param-description)
+ * [`require-jsdoc`](#user-content-eslint-plugin-jsdoc-rules-require-jsdoc)
+ * [`require-param-description`](#user-content-eslint-plugin-jsdoc-rules-require-param-description)
+ * [`require-param-name`](#user-content-eslint-plugin-jsdoc-rules-require-param-name)
+ * [`require-param-type`](#user-content-eslint-plugin-jsdoc-rules-require-param-type)
+ * [`require-param`](#user-content-eslint-plugin-jsdoc-rules-require-param)
+ * [`require-property`](#user-content-eslint-plugin-jsdoc-rules-require-property)
+ * [`require-property-description`](#user-content-eslint-plugin-jsdoc-rules-require-property-description)
+ * [`require-property-name`](#user-content-eslint-plugin-jsdoc-rules-require-property-name)
+ * [`require-property-type`](#user-content-eslint-plugin-jsdoc-rules-require-property-type)
+ * [`require-returns-check`](#user-content-eslint-plugin-jsdoc-rules-require-returns-check)
+ * [`require-returns-description`](#user-content-eslint-plugin-jsdoc-rules-require-returns-description)
+ * [`require-returns-type`](#user-content-eslint-plugin-jsdoc-rules-require-returns-type)
+ * [`require-returns`](#user-content-eslint-plugin-jsdoc-rules-require-returns)
+ * [`require-throws`](#user-content-eslint-plugin-jsdoc-rules-require-throws)
+ * [`require-yields`](#user-content-eslint-plugin-jsdoc-rules-require-yields)
+ * [`require-yields-check`](#user-content-eslint-plugin-jsdoc-rules-require-yields-check)
+ * [`sort-tags`](#user-content-eslint-plugin-jsdoc-rules-sort-tags)
+ * [`tag-lines`](#user-content-eslint-plugin-jsdoc-rules-tag-lines)
+ * [`valid-types`](#user-content-eslint-plugin-jsdoc-rules-valid-types)
+
+
+
## Installation
@@ -92,6 +94,7 @@ globally too. Otherwise, install it locally.
npm install --save-dev eslint-plugin-jsdoc
```
+
## Configuration
@@ -174,6 +177,7 @@ which enables the rules commented above as "recommended":
You can then selectively add to or override the recommended rules.
+
## Options
@@ -202,9 +206,11 @@ object supplied as the second argument in an array after the error level
}
```
+
## Settings
+
### Allow tags (@private
or @internal
) to disable rules for that comment block
@@ -217,6 +223,7 @@ object supplied as the second argument in an array after the error level
on which a `@internal` tag occurs. Defaults to `false`. Note: This has no
effect with the rule `empty-tags` (which checks `@internal` itself).
+
### maxLines
and minLines
@@ -229,6 +236,7 @@ be enforced so as to report problems if a jsdoc block is not found within
the specified boundaries. The settings are also used in the fixer to determine
how many line breaks to add when a block is missing.
+
### Mode
@@ -257,6 +265,7 @@ how many line breaks to add when a block is missing.
- Disallows namepath on `@interface` for "closure" mode in `valid-types` (and
avoids checking in other rules)
+
### Alias Preference
@@ -349,6 +358,7 @@ See `check-tag-names` for how that fact can be used to set an alias to itself
to allow both the alias and the default (since aliases are otherwise not
permitted unless used in `tagNamePreference`).
+
#### Default Preferred Aliases
@@ -388,6 +398,7 @@ This setting is utilized by the the rule for tag name checking
- `require-returns-description`
- `require-returns-type`
+
### @override
/@augments
/@extends
/@implements
/@ignore
Without Accompanying @param
/@description
/@example
/@returns
/@throws
/@yields
@@ -418,6 +429,7 @@ The format of the configuration is as follows:
}
```
+
### Settings to Configure check-types
and no-undefined-types
@@ -483,6 +495,7 @@ key nor the value will be reported. Thus in `check-types`, this fact can
be used to allow both `object` and `Object` if one has a `preferredTypes`
key `object: 'Object'` and `Object: 'object'`.
+
### structuredTags
@@ -528,9 +541,11 @@ values are objects with the following optional properties:
name (`@throws Some text`); does not require that both exist but
disallows just an empty tag.
+
## Advanced
+
### AST and Selectors
@@ -546,6 +561,7 @@ your files' code which are of interest to check. However, in
`eslint-plugin-jsdoc`, we also allow you to use these selectors to define
additional contexts where you wish our own rules to be applied.
+
#### contexts
format
@@ -582,6 +598,7 @@ properties:
function). See [@es-joy/jsdoccomment](https://github.com/es-joy/jsdoccomment)
for the precise structure of the comment (and comment type) nodes.
+
#### Discovering available AST definitions
@@ -602,6 +619,7 @@ providing some of your JavaScript to the wonderful
[AST Explorer](https://astexplorer.net/) tool and see what AST is built out
of your code. You can set the tool to the specific parser which you are using.
+
#### Uses/Tips for AST
@@ -623,9 +641,11 @@ to the selector you wish so as to get messages reported in the bottom right
pane which match your [esquery](https://github.com/estools/esquery/#readme)
selector).
+
## Rules
+
### check-access
@@ -800,6 +820,7 @@ function quux (foo) {
````
+
### check-alignment
@@ -943,6 +964,7 @@ function quux (foo) {
````
+
### check-examples
@@ -953,11 +975,13 @@ Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also
has options to lint the default values of optional `@param`/`@arg`/`@argument`
and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags.
+
#### Options
The options below all default to no-op/`false` except as noted.
+
##### captionRequired
@@ -969,6 +993,7 @@ the beginning of any `@example`.
Used only for `@example`.
+
##### exampleCodeRegex
and rejectExampleCodeRegex
@@ -998,6 +1023,7 @@ If neither is in use, all examples will be matched. Note also that even if
`captionRequired` is not set, any initial `
paddedIndent
@@ -1019,6 +1045,7 @@ out before evaluation.
Only applied to `@example` linting.
+
##### reportUnusedDisableDirectives
@@ -1031,6 +1058,7 @@ Inline ESLint config within `@example` JavaScript is allowed (or within
needed by the resolved rules will be reported as with the ESLint
`--report-unused-disable-directives` command.
+
#### Options for Determining ESLint Rule Applicability (allowInlineConfig
, noDefaultExampleRules
, matchingFileName
, configFile
, checkEslintrc
, and baseConfig
)
@@ -1083,6 +1111,7 @@ by decreasing precedence:
* `baseConfig` - Set to an object of rules with the same schema
as `.eslintrc.*` for defaults.
+
##### Rules Disabled by Default Unless noDefaultExampleRules
is Set to true
@@ -1119,6 +1148,7 @@ expression-oriented rules will be used by default as well:
* `no-unused-expressions` - Disabled.
* `chai-friendly/no-unused-expressions` - Disabled.
+
##### Options for checking other than @example
(checkDefaults
, checkParams
, or checkProperties
)
@@ -1692,6 +1722,7 @@ const functionName = function (paramOne, paramTwo,
````
+
### check-indentation
@@ -1711,11 +1742,13 @@ the following description is not reported:
*/
```
+
#### Options
This rule has an object option.
+
##### excludeTags
@@ -1965,6 +1998,7 @@ function MyDecorator(options: { myOptions: number }) {
````
+
### check-line-alignment
@@ -1972,6 +2006,7 @@ Reports invalid alignment of JSDoc block lines. This is a
[standard recommended to WordPress code](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/#aligning-comments),
for example.
+
#### Options
@@ -1985,6 +2020,7 @@ space is present after the asterisk delimiter.
After the string, an options object is allowed with the following properties.
+
##### tags
@@ -1992,6 +2028,7 @@ Use this to change the tags which are sought for alignment changes. *Currently*
*only works with the "never" option.* Defaults to an array of
`['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return']`.
+
##### customSpacings
@@ -2651,11 +2688,13 @@ const fn = ({ids}) => {}
````
+
### check-param-names
Ensures that parameter names in JSDoc match those in the function declaration.
+
#### Destructuring
@@ -2682,19 +2721,23 @@ other properties, so in looking at the docs alone without looking at the
function signature, the disadvantage of enabling this option is that it
may appear that there is an actual property named `extra`.
+
#### Options
+
##### checkRestProperty
See the "Destructuring" section. Defaults to `false`.
+
##### checkTypesPattern
See `require-param` under the option of the same name.
+
##### enableFixer
@@ -2705,6 +2748,7 @@ Note that this option will remove duplicates of the same name even if
the definitions do not match in other ways (e.g., the second param will
be removed even if it has a different type or description).
+
##### allowExtraTrailingParamDocs
@@ -2713,11 +2757,13 @@ representing future expected or virtual params) to be present without needing
their presence within the function signature. Other inconsistencies between
`@param`'s and present function parameters will still be reported.
+
##### checkDestructured
Whether to check destructured properties. Defaults to `true`.
+
##### useDefaultObjectProperties
@@ -2726,6 +2772,7 @@ where instead of destructuring, a whole plain object is supplied as default
value but you wish its keys to be considered as signalling that the properties
are present and can therefore be documented. Defaults to `false`.
+
##### disableExtraPropertyReporting
@@ -3598,15 +3645,18 @@ const foo = ([, b]) => b;
````
+
### check-property-names
Ensures that property names in JSDoc are not duplicated on the same block
and that nested properties have defined roots.
+
#### Options
+
##### enableFixer
@@ -3812,6 +3862,7 @@ function quux (code = 1) {
````
+
### check-syntax
@@ -3873,6 +3924,7 @@ function quux (foo) {
````
+
### check-tag-names
@@ -4050,9 +4102,11 @@ typeSummary
wizaction
```
+
#### Options
+
##### definedTags
@@ -4065,6 +4119,7 @@ The format is as follows:
}
```
+
#### jsxTags
@@ -4713,6 +4768,7 @@ export function transientcheck-types
@@ -4736,6 +4792,7 @@ Date
RegExp
```
+
#### Options
@@ -4785,6 +4842,7 @@ Note that if there is an error [parsing](https://github.com/jsdoc-type-pratt-par
types for a tag, the function will silently ignore that tag, leaving it to
the `valid-types` rule to report parsing errors.
+
#### Why not capital case everything?
@@ -5802,6 +5860,7 @@ function a () {}
````
+
### check-values
@@ -5822,21 +5881,25 @@ This rule checks the values for a handful of tags:
'constant', 'event', 'external', 'file', 'function', 'member', 'mixin',
'module', 'namespace', 'typedef',
+
#### Options
+
##### allowedAuthors
An array of allowable author values. If absent, only non-whitespace will
be checked for.
+
##### allowedLicenses
An array of allowable license values or `true` to allow any license text.
If present as an array, will be used in place of SPDX identifiers.
+
##### licensePattern
@@ -5851,6 +5914,7 @@ Note that the `/` delimiters are optional, but necessary to add flags.
Defaults to using the `u` flag, so to add your own flags, encapsulate
your expression as a string, but like a literal, e.g., `/^mit$/ui`.
+
##### numericOnlyVariation
@@ -6137,6 +6201,7 @@ function quux (foo) {
````
+
### empty-tags
@@ -6171,9 +6236,11 @@ causes rules not to take effect).
Similarly, `@internal` will still be checked for content by this rule even with
`settings.jsdoc.ignoreInternal` set to `true`.
+
#### Options
+
##### tags
@@ -6332,6 +6399,7 @@ function quux () {}
````
+
### implements-on-classes
@@ -6344,9 +6412,11 @@ To indicate that a function follows another function's signature, one might
instead use `@type` to indicate the `@function` or `@callback` to which the
function is adhering.
+
#### Options
+
##### contexts
@@ -6359,7 +6429,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -6528,6 +6598,7 @@ function quux () {
````
+
### match-description
@@ -6555,9 +6626,11 @@ case-insensitive unless one opts in to add the `i` flag.
You can add the `s` flag if you want `.` to match newlines. Note, however,
that the trailing newlines of a description will not be matched.
+
#### Options
+
##### matchDescription
@@ -6570,6 +6643,7 @@ You can supply your own expression to override the default, passing a
}
```
+
##### message
@@ -6586,6 +6660,7 @@ You may provide a custom default message by using the following format:
This can be overridden per tag or for the main block description by setting
`message` within `tags` or `mainDescription`, respectively.
+
##### tags
@@ -6635,6 +6710,7 @@ its "description" (e.g., for `@returns {someType} some description`, the
description is `some description` while for `@some-tag xyz`, the description
is `xyz`).
+
##### mainDescription
@@ -6675,6 +6751,7 @@ You may also provide an object with `message`:
}
```
+
##### contexts
@@ -6684,7 +6761,7 @@ Set this to an array of strings representing the AST context (or an object with
classes). Overrides the default contexts (see below). Set to `"any"` if you
want the rule to apply to any jsdoc block throughout your files.
-See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -7432,6 +7509,7 @@ function quux () {
````
+
### match-name
@@ -7444,11 +7522,13 @@ name will actually be part of the description (e.g., for
`structuredTags` setting (if `name: false`, this rule will not apply to
that tag).
+
#### Options
A single options object with the following properties:
+
##### match
@@ -7473,7 +7553,7 @@ properties, all of which act to confine one another:
- `context` - AST to confine the allowing or disallowing to jsdoc blocks
associated with a particular context. See the
- ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+ ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
- `comment` - As with `context` but AST for the JSDoc block comment and types
@@ -7643,6 +7723,7 @@ class A {
````
+
### multiline-blocks
@@ -7655,11 +7736,13 @@ all jsdoc blocks!
Also allows for preventing text at the very beginning or very end of blocks.
+
#### Options
A single options object with the following properties.
+
##### noZeroLineText
(defaults to true
)
@@ -7668,6 +7751,7 @@ space will be reported. (Text after a newline is not reported.)
`noMultilineBlocks` will have priority over this rule if it applies.
+
##### noFinalLineText
(defaults to true
)
@@ -7676,12 +7760,14 @@ line will be reported. (Text preceding a newline is not reported.)
`noMultilineBlocks` will have priority over this rule if it applies.
+
##### noSingleLineBlocks
(defaults to false
)
If this is `true`, any single line blocks will be reported, except those which
are whitelisted in `singleLineTags`.
+
##### singleLineTags
(defaults to ['lends', 'type']
)
@@ -7691,6 +7777,7 @@ cause all single line blocks to be reported. If `'*'` is present, then
the presence of a tag will allow single line blocks (but not if a tag is
missing).
+
##### noMultilineBlocks
(defaults to false
)
@@ -7698,6 +7785,7 @@ Requires that jsdoc blocks are restricted to single lines only unless impacted
by the options `minimumLengthForMultiline`, `multilineTags`, or
`allowMultipleTags`.
+
##### minimumLengthForMultiline
(defaults to not being in effect)
@@ -7707,6 +7795,7 @@ be permitted if containing at least the given amount of text.
If not set, multiline blocks will not be permitted regardless of length unless
a relevant tag is present and `multilineTags` is set.
+
##### multilineTags
(defaults to ['*']
)
@@ -7723,6 +7812,7 @@ such a tag will cause multiline blocks to be allowed.
You may set this to an empty array to prevent any tag from permitting multiple
lines.
+
##### allowMultipleTags
(defaults to true
)
@@ -8010,11 +8100,13 @@ The following patterns are not considered problems:
````
+
### newline-after-description
Enforces a consistent padding of the block description.
+
#### Options
@@ -8249,6 +8341,7 @@ function example() {
````
+
### no-bad-blocks
@@ -8258,11 +8351,13 @@ 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).
+
#### Options
Takes an optional options object with the following.
+
##### ignore
@@ -8272,6 +8367,7 @@ 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)).
+
##### preventAllMultiAsteriskBlocks
@@ -8394,6 +8490,7 @@ function quux (foo) {
````
+
### no-defaults
@@ -8409,9 +8506,11 @@ 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".
+
#### Options
+
##### noOptionalParamNames
@@ -8421,6 +8520,7 @@ 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).
+
##### contexts
@@ -8432,7 +8532,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -8569,6 +8669,7 @@ const a = {};
````
+
### no-missing-syntax
@@ -8606,9 +8707,11 @@ which are not adequate to satisfy a condition, e.g.,
not report if there were only a function declaration of the name "ignoreMe"
(though it would report by function declarations of other names).
+
#### Options
+
##### contexts
@@ -8627,7 +8730,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -8806,6 +8909,7 @@ function quux () {
````
+
### no-multi-asterisks
@@ -8815,9 +8919,11 @@ Note that if you wish to prevent multiple asterisks at the very beginning of
the jsdoc block, you should use `no-bad-blocks` (as that is not proper jsdoc
and that rule is for catching blocks which only seem like jsdoc).
+
#### Options
+
##### allowWhitespace
(defaults to false
)
@@ -8829,6 +8935,7 @@ Set to `true` if you wish to allow asterisks after a space (as with Markdown):
*/
```
+
##### preventAtMiddleLines
(defaults to true
)
@@ -8841,6 +8948,7 @@ Prevent the likes of this:
*/
```
+
##### preventAtEnd
(defaults to true
)
@@ -9058,6 +9166,7 @@ function foo() {
````
+
### no-restricted-syntax
@@ -9075,9 +9184,11 @@ structures, (whether or not you add a specific `comment` condition).
Note that if your parser supports comment AST (as [jsdoc-eslint-parser](https://github.com/brettz9/jsdoc-eslint-parser)
is designed to do), you can just use ESLint's rule.
+
#### Options
+
##### contexts
@@ -9092,7 +9203,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -9270,6 +9381,7 @@ const MY_ENUM = Object.freeze({
````
+
### no-types
@@ -9278,9 +9390,11 @@ This rule reports types being used on `@param` or `@returns`.
The rule is intended to prevent the indication of types on tags where
the type information would be redundant with TypeScript.
+
#### Options
+
##### contexts
@@ -9292,7 +9406,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -9405,6 +9519,7 @@ function quux (foo) {
````
+
### no-undefined-types
@@ -9451,6 +9566,7 @@ reporting on use of that namepath elsewhere) and/or that a tag's `type` is
`false` (and should not be checked for types). If the `type` is an array, that
array's items will be considered as defined for the purposes of that tag.
+
#### Options
@@ -10076,11 +10192,13 @@ export class Foo {
````
+
### require-asterisk-prefix
Requires that each JSDoc line starts with an `*`.
+
#### Options
@@ -10092,6 +10210,7 @@ and use the `tags` option to apply to specific tags only.
After the string option, one may add an object with the following.
+
##### tags
@@ -10349,6 +10468,7 @@ function quux (foo) {
````
+
### require-description-complete-sentence
@@ -10366,9 +10486,11 @@ Requires that block description, explicit `@description`, and
* Periods after items within the `abbreviations` option array are not treated
as sentence endings.
+
#### Options
+
##### tags
@@ -10393,6 +10515,7 @@ its "description" (e.g., for `@returns {someType} some description`, the
description is `some description` while for `@some-tag xyz`, the description
is `xyz`).
+
##### abbreviations
@@ -10400,6 +10523,7 @@ You can provide an `abbreviations` options array to avoid such strings of text
being treated as sentence endings when followed by dots. The `.` is not
necessary at the end of the array items.
+
##### newlineBeforeCapsAssumesBadSentenceEnd
@@ -11059,6 +11183,7 @@ export default (foo) => {
````
+
### require-description
@@ -11071,6 +11196,7 @@ Requires that all functions have a description.
is `"tag"`) must have a non-empty description that explains the purpose of
the method.
+
#### Options
@@ -11612,6 +11738,7 @@ class quux {
````
+
### require-example
@@ -11621,11 +11748,13 @@ Requires that all functions have examples.
* Every example tag must have a non-empty description that explains the
method's usage.
+
#### Options
This rule has an object option.
+
##### exemptedBy
@@ -11635,12 +11764,14 @@ block avoids the need for an `@example`. Defaults to an array with
so be sure to add back `inheritdoc` if you wish its presence to cause
exemption of the rule.
+
##### exemptNoArguments
Boolean to indicate that no-argument functions should not be reported for
missing `@example` declarations.
+
##### contexts
@@ -11650,25 +11781,29 @@ Set this to an array of strings representing the AST context (or an object with
classes). Overrides the default contexts (see below). Set to `"any"` if you
want the rule to apply to any jsdoc block throughout your files.
-See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
+
##### checkConstructors
A value indicating whether `constructor`s should be checked.
Defaults to `true`.
+
##### checkGetters
A value indicating whether getters should be checked. Defaults to `false`.
+
##### checkSetters
A value indicating whether setters should be checked. Defaults to `false`.
+
#### Fixer
@@ -11943,6 +12078,7 @@ function quux () {
````
+
### require-file-overview
@@ -11956,9 +12092,11 @@ Checks that:
as being when the overview tag is not preceded by anything other than
a comment.
+
#### Options
+
##### tags
@@ -12237,11 +12375,13 @@ function quux () {
````
+
### require-hyphen-before-param-description
Requires (or disallows) a hyphen before the `@param` description.
+
#### Options
@@ -12467,17 +12607,20 @@ function main(argv) {
````
+
### require-jsdoc
Checks for presence of jsdoc comments, on class declarations as well as
functions.
+
#### Options
Accepts one optional options object with the following optional keys.
+
##### publicOnly
@@ -12494,6 +12637,7 @@ otherwise noted):
- `cjs` - CommonJS exports are checked for JSDoc comments (Defaults to `true`)
- `window` - Window global exports are checked for JSDoc comments
+
##### require
@@ -12507,6 +12651,7 @@ An object with the following optional boolean keys which all default to
- `FunctionExpression`
- `MethodDefinition`
+
##### contexts
@@ -12520,9 +12665,10 @@ block which will otherwise be added. Defaults to an empty array.
Note that you may need to disable `require` items (e.g., `MethodDefinition`)
if you are specifying a more precise form in `contexts` (e.g., `MethodDefinition:not([accessibility="private"] > FunctionExpression`).
-See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
+
##### exemptEmptyConstructors
@@ -12532,6 +12678,7 @@ When `true`, the rule will not report missing jsdoc blocks above constructors
with no parameters or return values (this is enabled by default as the class
name or description should be seen as sufficient to convey intent).
+
##### exemptEmptyFunctions
@@ -12541,6 +12688,7 @@ When `true`, the rule will not report missing jsdoc blocks above
functions/methods with no parameters or return values (intended where
function/method names are sufficient for themselves as documentation).
+
##### checkConstructors
@@ -12548,6 +12696,7 @@ A value indicating whether `constructor`s should be checked. Defaults to
`true`. When `true`, `exemptEmptyConstructors` may still avoid reporting when
no parameters or return values are found.
+
##### checkGetters
@@ -12557,6 +12706,7 @@ getters should be checked but only when there is no setter. This may be useful
if one only wishes documentation on one of the two accessors. Defaults to
`false`.
+
##### checkSetters
@@ -12566,6 +12716,7 @@ setters should be checked but only when there is no getter. This may be useful
if one only wishes documentation on one of the two accessors. Defaults to
`false`.
+
##### enableFixer
@@ -14156,14 +14307,17 @@ export class User {
````
+
### require-param-description
Requires that each `@param` tag has a `description` value.
+
#### Options
+
##### contexts
@@ -14175,7 +14329,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -14276,6 +14430,7 @@ function quux (foo) {
````
+
### require-param-name
@@ -14285,9 +14440,11 @@ Requires that all function parameters have names.
>
> [JSDoc](https://jsdoc.app/tags-param.html#overview)
+
#### Options
+
##### contexts
@@ -14299,7 +14456,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -14416,14 +14573,17 @@ function example(cb) {
````
+
### require-param-type
Requires that each `@param` tag has a `type` value.
+
#### Options
+
##### contexts
@@ -14435,7 +14595,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -14536,11 +14696,13 @@ function quux (foo) {
````
+
### require-param
Requires that all function parameters are documented.
+
#### Fixer
@@ -14548,6 +14710,7 @@ Adds `@param RestElement
) insertions
@@ -14687,6 +14852,7 @@ function baar ([a, ...extra]) {
...because it does not use the `...` syntax in the type.
+
##### Object Rest Property insertions
@@ -14722,16 +14888,19 @@ other properties, so in looking at the docs alone without looking at the
function signature, it may appear that there is an actual property named
`extra`.
+
#### Options
An options object accepts the following optional properties:
+
##### enableFixer
Whether to enable the fixer. Defaults to `true`.
+
##### enableRootFixer
@@ -14739,12 +14908,14 @@ Whether to enable the auto-adding of incrementing roots (see the "Fixer"
section). Defaults to `true`. Has no effect if `enableFixer` is set to
`false`.
+
##### enableRestElementFixer
Whether to enable the rest element fixer (see
"Rest Element (`RestElement`) insertions"). Defaults to `true`.
+
##### checkRestProperty
@@ -14799,12 +14970,14 @@ function quux ({num, ...extra}) {
}
```
+
##### autoIncrementBase
Numeric to indicate the number at which to begin auto-incrementing roots.
Defaults to `0`.
+
##### unnamedRootBase
@@ -14831,6 +15004,7 @@ function quux ({foo}, [bar], {baz}) {
*/
```
+
##### exemptedBy
@@ -14840,6 +15014,7 @@ avoids the need for a `@param`. Defaults to an array with
so be sure to add back `inheritdoc` if you wish its presence to cause
exemption of the rule.
+
##### checkTypesPattern
@@ -14875,6 +15050,7 @@ You could set this regular expression to a more expansive list, or you
could restrict it such that even types matching those strings would not
need destructuring.
+
##### contexts
@@ -14884,30 +15060,35 @@ Overrides the default contexts (see below). May be useful for adding such as
`TSMethodSignature` in TypeScript or restricting the contexts
which are checked.
-See the ["AST and Selectors"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
+
##### checkConstructors
A value indicating whether `constructor`s should be checked. Defaults to
`true`.
+
##### checkGetters
A value indicating whether getters should be checked. Defaults to `false`.
+
##### checkSetters
A value indicating whether setters should be checked. Defaults to `false`.
+
##### checkDestructured
Whether to require destructured properties. Defaults to `true`.
+
##### checkDestructuredRoots
@@ -14921,6 +15102,7 @@ implied to be `false` (i.e., the inside of the roots will not be checked
either, e.g., it will also not complain if `a` or `b` do not have their own
documentation). Defaults to `true`.
+
##### useDefaultObjectProperties
@@ -16264,6 +16446,7 @@ export function testFn1 ({ prop = { a: 1, b: 2 } }) {
````
+
### require-property
@@ -16273,6 +16456,7 @@ when their type is a plain `object`, `Object`, or `PlainObject`.
Note that any other type, including a subtype of object such as
`objectrequire-property-description
@@ -16440,6 +16625,7 @@ The following patterns are not considered problems:
````
+
### require-property-name
@@ -16500,6 +16686,7 @@ The following patterns are not considered problems:
````
+
### require-property-type
@@ -16560,6 +16747,7 @@ The following patterns are not considered problems:
````
+
### require-returns-check
@@ -16572,6 +16760,7 @@ is set to `false` no non-`undefined` returned or resolved value is found.
Will also report if multiple `@returns` tags are present.
+
#### Options
@@ -17149,6 +17338,7 @@ function * quux() {}
````
+
### require-returns-description
@@ -17156,9 +17346,11 @@ Requires that the `@returns` tag has a `description` value. The error
will not be reported if the return value is `void` or `undefined`
or if it is `Promisecontexts
@@ -17170,7 +17362,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -17307,14 +17499,17 @@ function quux () {
````
+
### require-returns-type
Requires that `@returns` tag has `type` value.
+
#### Options
+
##### contexts
@@ -17326,7 +17521,7 @@ 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"](#eslint-plugin-jsdoc-advanced-ast-and-selectors)
+See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
section of our README for more on the expected format.
|||
@@ -17428,6 +17623,7 @@ function quux () {
````
+
### require-returns
@@ -17435,6 +17631,7 @@ Requires that returns are documented.
Will also report if multiple `@returns` tags are present.
+
#### Options
@@ -18518,11 +18715,13 @@ export const sleep = (ms: number) => {
````
+
### require-throws
Requires that throw statements are documented.
+
#### Options
@@ -18816,6 +19015,7 @@ function quux (foo) {
````
+
### require-yields
@@ -18826,6 +19026,7 @@ Will also report if multiple `@yields` tags are present.
See the `next`, `forceRequireNext`, and `nextWithGeneratorTag` options for an
option to expect a non-standard `@next` tag.
+
#### Options
@@ -19618,6 +19819,7 @@ function * quux (foo) {
````
+
### require-yields-check
@@ -19636,6 +19838,7 @@ function bodies.
Will also report if multiple `@yields` tags are present.
+
#### Options
@@ -20140,6 +20343,7 @@ function * quux (foo) {
````
+
### sort-tags
@@ -20147,9 +20351,11 @@ Sorts tags by a specified sequence according to tag name.
(Default order originally inspired by [`@homer0/prettier-plugin-jsdoc`](https://github.com/homer0/packages/tree/main/packages/public/prettier-plugin-jsdoc).)
+
#### Options
+
##### tagSequence
@@ -20326,6 +20532,7 @@ a fixed order that doesn't change into the future, supply your own
];
```
+
##### alphabetizeExtras
@@ -20477,11 +20684,13 @@ function quux () {}
````
+
### tag-lines
Enforces lines (or no lines) between tags.
+
#### Options
@@ -20493,17 +20702,20 @@ for particular tags).
The second option is an object with the following optional properties.
+
##### count
(defaults to 1)
Use with "always" to indicate the number of lines to require be present.
+
##### noEndLines
(defaults to false
)
Use with "always" to indicate the normal lines to be added after tags should
not be added after the final tag.
+
##### tags
(default to empty object)
@@ -20820,13 +21032,14 @@ The following patterns are not considered problems:
````
+
### valid-types
Requires all types to be valid JSDoc, Closure, or TypeScript compiler types
without syntax errors. Note that what determines a valid type is handled by
our type parsing engine, [jsdoc-type-pratt-parser](https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser),
-using [`settings.jsdoc.mode`](#eslint-plugin-jsdoc-settings-mode) to
+using [`settings.jsdoc.mode`](#user-content-eslint-plugin-jsdoc-settings-mode) to
determine whether to use jsdoc-type-pratt-parser's "permissive" parsing or
the stricter "jsdoc", "typescript", "closure" modes.
@@ -20900,6 +21113,7 @@ for valid types (based on the tag's `type` value), and either portion checked
for presence (based on `false` `name` or `type` values or their `required`
value). See the setting for more details.
+
#### Options
diff --git a/package.json b/package.json
index 7e63394e0..5251f63a9 100644
--- a/package.json
+++ b/package.json
@@ -16,7 +16,7 @@
},
"description": "JSDoc linting rules for ESLint.",
"devDependencies": {
- "@babel/cli": "^7.17.3",
+ "@babel/cli": "^7.17.6",
"@babel/core": "^7.17.5",
"@babel/eslint-parser": "^7.17.0",
"@babel/node": "^7.16.8",
@@ -25,26 +25,26 @@
"@babel/preset-env": "^7.16.11",
"@babel/register": "^7.17.0",
"@hkdobrev/run-if-changed": "^0.3.1",
- "@typescript-eslint/parser": "^5.12.0",
+ "@typescript-eslint/parser": "^5.13.0",
"babel-plugin-add-module-exports": "^1.0.4",
"babel-plugin-istanbul": "^6.1.1",
"camelcase": "^6.3.0",
"chai": "^4.3.6",
"cross-env": "^7.0.3",
"decamelize": "^5.0.1",
- "eslint": "^8.9.0",
+ "eslint": "^8.10.0",
"eslint-config-canonical": "^33.0.1",
- "gitdown": "^3.1.4",
+ "gitdown": "^3.1.5",
"glob": "^7.2.0",
"husky": "^7.0.4",
"lint-staged": "^12.3.4",
"lodash.defaultsdeep": "^4.6.1",
- "mocha": "^9.2.0",
+ "mocha": "^9.2.1",
"nyc": "^15.1.0",
"open-editor": "^3.0.0",
"rimraf": "^3.0.2",
"semantic-release": "^19.0.2",
- "typescript": "^4.5.5"
+ "typescript": "^4.6.2"
},
"engines": {
"node": "^12 || ^14 || ^16 || ^17"