eslint-plugin-jsdoc 46.4.6 → 46.5.0

package/docs/rules/no-missing-syntax.md

@@ -1,275 +0,0 @@
-<a name="user-content-no-missing-syntax"></a>
-<a name="no-missing-syntax"></a>
-# <code>no-missing-syntax</code>
-
-* [Options](#user-content-no-missing-syntax-options)
-    * [`contexts`](#user-content-no-missing-syntax-options-contexts)
-* [Context and settings](#user-content-no-missing-syntax-context-and-settings)
-* [Failing examples](#user-content-no-missing-syntax-failing-examples)
-* [Passing examples](#user-content-no-missing-syntax-passing-examples)
-
-
-This rule lets you report if certain always expected comment structures are
-missing.
-
-This (along with `no-restricted-syntax`) is a bit similar to Schematron for
-XML or jsontron for JSON--you can validate expectations of there being
-arbitrary structures.
-
-This differs from the rule of the same name in
-[`eslint-plugin-query`](https://github.com/brettz9/eslint-plugin-query)
-in that this rule always looks for a comment above a structure (whether or not
-you have a `comment` condition).
-
-This rule might be especially useful with [`overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#how-do-overrides-work)
-where you need only require tags and/or types within specific directories
-(e.g., to enforce that a plugins or locale directory always has a certain form
-of export and comment therefor).
-
-In addition to being generally useful for precision in requiring contexts,
-it is hoped that the ability to specify required tags on structures can
-be used for requiring `@type` or other types for a minimalist yet adequate
-specification of types which can be used to compile JavaScript+JSDoc (JJ)
-to WebAssembly (e.g., by converting it to TypeSscript and then using
-AssemblyScript to convert to WebAssembly). (It may be possible that one
-will need to require types with certain structures beyond function
-declarations and the like, as well as optionally requiring specification
-of number types.)
-
-Note that you can use selectors which make use of negators like `:not()`
-including with asterisk, e.g., `*:not(FunctionDeclaration)` to indicate types
-which are not adequate to satisfy a condition, e.g.,
-`FunctionDeclaration:not(FunctionDeclaration[id.name="ignoreMe"])` would
-not report if there were only a function declaration of the name "ignoreMe"
-(though it would report by function declarations of other names).
-
-<a name="user-content-no-missing-syntax-options"></a>
-<a name="no-missing-syntax-options"></a>
-## Options
-
-<a name="user-content-no-missing-syntax-options-contexts"></a>
-<a name="no-missing-syntax-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.
-
-Use the `minimum` property (defaults to 1) to indicate how many are required
-for the rule to be reported.
-
-Use the `message` property to indicate the specific error to be shown when an
-error is reported for that context being found missing. You may use
-`{{context}}` and `{{comment}}` with such messages.
-
-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-missing-syntax-context-and-settings"></a>
-<a name="no-missing-syntax-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|None except those indicated by `contexts`|
-|Tags|Any if indicated by AST|
-|Recommended|false|
-|Options|`contexts`|
-
-<a name="user-content-no-missing-syntax-failing-examples"></a>
-<a name="no-missing-syntax-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(1))","context":"FunctionDeclaration"}]}]
-// Message: Syntax is required: FunctionDeclaration with JsdocBlock[postDelimiter=""]:has(JsdocTypeUnion > JsdocTypeName[value="Foo"]:nth-child(1))
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// Settings: {"jsdoc":{"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(1))","context":"FunctionDeclaration"}]}}
-// Message: Syntax is required: FunctionDeclaration with JsdocBlock[postDelimiter=""]:has(JsdocTypeUnion > JsdocTypeName[value="Foo"]:nth-child(1))
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"FunctionDeclaration"},{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(1))","context":"FunctionDeclaration"}]}]
-// Message: Syntax is required: FunctionDeclaration with JsdocBlock[postDelimiter=""]:has(JsdocTypeUnion > JsdocTypeName[value="Foo"]:nth-child(1))
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"any"},{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(1))","context":":function"}]}]
-// Message: Syntax is required: :function with JsdocBlock[postDelimiter=""]:has(JsdocTypeUnion > JsdocTypeName[value="Foo"]:nth-child(1))
-
-/**
- * @private
- * Object holding values of some custom enum
- */
-const MY_ENUM = Object.freeze({
-  VAL_A: "myvala"
-} as const);
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[tag=/private|protected/])","context":":declaration","message":"Requiring private/protected tags here"},{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTag[tag=\"enum\"])","context":"any","message":"@enum required on declarations"}]}]
-// Message: @enum required on declarations
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(1))","context":"FunctionDeclaration","message":"Problematically missing function syntax: `{{context}}` with `{{comment}}`."}]}]
-// Message: Problematically missing function syntax: `FunctionDeclaration` with `JsdocBlock[postDelimiter=""]:has(JsdocTypeUnion > JsdocTypeName[value="Foo"]:nth-child(1))`.
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":["FunctionDeclaration"]}]
-// Message: Syntax is required: FunctionDeclaration
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// Message: Rule `no-missing-syntax` is missing a `contexts` option.
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"FunctionDeclaration","minimum":2}]}]
-// Message: Syntax is required: FunctionDeclaration with JsdocBlock[postDelimiter=""]:has(JsdocTypeUnion > JsdocTypeName[value="Bar"]:nth-child(1))
-
-/**
- * @param ab
- * @param cd
- */
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag[name=/opt_/])","context":"any","message":"Require names matching `/^opt_/i`."}]}]
-// Message: Require names matching `/^opt_/i`.
-
-/**
- * @param ab
- * @param cd
- */
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag[name=/opt_/])","message":"Require names matching `/^opt_/i`."}]}]
-// Message: Require names matching `/^opt_/i`.
-
-/**
- * @param ab
- * @param cd
- */
-function quux () {}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag[name=/opt_/])","context":"any","message":"Require names matching `/^opt_/i`."}]}]
-// Message: Require names matching `/^opt_/i`.
-
-/**
- * @implements {Bar|Foo}
- */
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"context":"FunctionDeclaration"}]}]
-// Message: Syntax is required: FunctionDeclaration
-````
-
-
-
-<a name="user-content-no-missing-syntax-passing-examples"></a>
-<a name="no-missing-syntax-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"FunctionDeclaration"}]}]
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-
-/**
- * @implements {Bar|Foo}
- */
-function bar () {
-
-}
-
-/**
- * @implements {Bar|Foo}
- */
-function baz () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"FunctionDeclaration","minimum":2}]}]
-
-/**
- * @param opt_a
- * @param opt_b
- */
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag[name=/opt_/])","context":"any","message":"Require names matching `/^opt_/i`."}]}]
-
-/**
- * @param opt_a
- * @param opt_b
- */
-function quux () {}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag[name=/opt_/])","context":"any","message":"Require names matching `/^opt_/i`."}]}]
-
-/**
- * @param opt_a
- * @param opt_b
- */
-function quux () {}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock:has(JsdocTag[name=/opt_/])","message":"Require names matching `/^opt_/i`."}]}]
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"FunctionDeclaration"},{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(2))","context":"FunctionDeclaration"}]}]
-
-/**
- * @implements {Bar|Foo}
- */
-function quux () {
-
-}
-// "jsdoc/no-missing-syntax": ["error"|"warn", {"contexts":[{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Bar\"]:nth-child(1))","context":"any"},{"comment":"JsdocBlock[postDelimiter=\"\"]:has(JsdocTypeUnion > JsdocTypeName[value=\"Foo\"]:nth-child(2))","context":"FunctionDeclaration"}]}]
-````
-

package/docs/rules/no-multi-asterisks.md

@@ -1,278 +0,0 @@
-<a name="user-content-no-multi-asterisks"></a>
-<a name="no-multi-asterisks"></a>
-### <code>no-multi-asterisks</code>
-
-
-
-Prevents use of multiple asterisks at the beginning of lines.
-
-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).
-
-<a name="user-content-fixer"></a>
-<a name="fixer"></a>
-## Fixer
-
-(TODO)
-
-<a name="user-content-options"></a>
-<a name="options"></a>
-## Options
-
-<a name="user-content-options-allowwhitespace-defaults-to-false"></a>
-<a name="options-allowwhitespace-defaults-to-false"></a>
-### <code>allowWhitespace</code> (defaults to <code>false</code>)
-
-Set to `true` if you wish to allow asterisks after a space (as with Markdown):
-
-```js
-/**
- * *bold* text
- */
-```
-
-<a name="user-content-options-preventatmiddlelines-defaults-to-true"></a>
-<a name="options-preventatmiddlelines-defaults-to-true"></a>
-### <code>preventAtMiddleLines</code> (defaults to <code>true</code>)
-
-Prevent the likes of this:
-
-```js
-/**
- *
- **
- */
-```
-
-<a name="user-content-options-preventatend-defaults-to-true"></a>
-<a name="options-preventatend-defaults-to-true"></a>
-### <code>preventAtEnd</code> (defaults to <code>true</code>)
-
-Prevent the likes of this:
-
-```js
-/**
- *
- *
- **/
-```
-
-<a name="user-content-context-and-settings"></a>
-<a name="context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|everywhere|
-|Tags|(any)|
-|Recommended|true|
-|Settings||
-|Options|`allowWhitespace`, `preventAtEnd`, `preventAtMiddleLines`|
-
-<a name="user-content-failing-examples"></a>
-<a name="failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- *
- **
- */
-// Message: Should be no multiple asterisks on middle lines.
-
-/**
- *
- **
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtMiddleLines":true}]
-// Message: Should be no multiple asterisks on middle lines.
-
-/**
- *
- **
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":false}]
-// Message: Should be no multiple asterisks on middle lines.
-
-/**
- * With a description
- * @tag {SomeType} and a tag with details
- **
- */
-// Message: Should be no multiple asterisks on middle lines.
-
-/**
- **
- *
- */
-// Message: Should be no multiple asterisks on middle lines.
-
-/**
- * Desc.
- *
- **/
-// Message: Should be no multiple asterisks on end lines.
-
-/**
- * Desc.
- *
- **/
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}]
-// Message: Should be no multiple asterisks on end lines.
-
-/**
- * Desc.
- *
- abc * **/
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}]
-// Message: Should be no multiple asterisks on end lines.
-
-/**
- * Desc.
- *
- **/
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtMiddleLines":false}]
-// Message: Should be no multiple asterisks on end lines.
-
-/** Desc. **/
-// Message: Should be no multiple asterisks on end lines.
-
-/** @someTag name desc. **/
-// Message: Should be no multiple asterisks on end lines.
-
-/** abc * */
-// Message: Should be no multiple asterisks on end lines.
-
-/**
- * Preserve user's whitespace when fixing (though one may also
- *   use an align rule)
- *
- * */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}]
-// Message: Should be no multiple asterisks on end lines.
-
-/**
- * The method does 2 things:
- * * Thing 1
- * * Thing 2
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":false}]
-// Message: Should be no multiple asterisks on middle lines.
-
-/**
- * This muti-line comment contains some
- * *non-standard bold* syntax
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":false}]
-// Message: Should be no multiple asterisks on middle lines.
-
-/** Desc. **/
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
-// Message: Should be no multiple asterisks on end lines.
-````
-
-
-
-<a name="user-content-passing-examples"></a>
-<a name="passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- *
- * Desc. ***
- */
-
-/**
- * Desc. ***
- *
- */
-
-/**
- * Desc.
- *
- * sth */
-
-/**
- **
- *
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtMiddleLines":false}]
-
-/**
- *
- *
- **/
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":false}]
-
-/**
- * With a desc.
- * and ***
- */
-
-/**
- * and ***
- * With a desc.
- */
-
-/**
- * With a desc.
- * With a desc.
- * Desc. */
-
-/**
- * With a description
- * @tag {SomeType} and a tag with details
- *
- */
-
-/** abc */
-function foo() {
-    //
-}
-
-/** foo */
-function foo(): void {
-    //
-}
-
-/** @aTag abc */
-function foo() {
-    //
-}
-
-/**
- * **Bold**
- */
-
-/**
- * Preserve user's bold statement when fixing.
- *
- * **Bold example:** Hi there.
- */
-
-/**
- * The method does 2 things:
- * * Thing 1
- * * Thing 2
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
-
-/**
- * This muti-line comment contains some
- * *non-standard bold* syntax
- */
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
-
-/** abc */
-function foo() {
-    //
-}
-// "jsdoc/no-multi-asterisks": ["error"|"warn", {"allowWhitespace":true}]
-````
-