eslint-plugin-jsdoc 46.4.5 → 46.5.0

package/docs/rules/require-example.md

@@ -1,390 +0,0 @@
-<a name="user-content-require-example"></a>
-<a name="require-example"></a>
-# <code>require-example</code>
-
-* [Fixer](#user-content-require-example-fixer)
-* [Options](#user-content-require-example-options)
-    * [`exemptedBy`](#user-content-require-example-options-exemptedby)
-    * [`exemptNoArguments`](#user-content-require-example-options-exemptnoarguments)
-    * [`contexts`](#user-content-require-example-options-contexts)
-    * [`checkConstructors`](#user-content-require-example-options-checkconstructors)
-    * [`checkGetters`](#user-content-require-example-options-checkgetters)
-    * [`checkSetters`](#user-content-require-example-options-checksetters)
-    * [`enableFixer`](#user-content-require-example-options-enablefixer)
-* [Context and settings](#user-content-require-example-context-and-settings)
-
-
-Requires that all functions have examples.
-
-* All functions must have one or more `@example` tags.
-* Every example tag must have a non-empty description that explains the
-  method's usage.
-
-<a name="user-content-require-example-fixer"></a>
-<a name="require-example-fixer"></a>
-## Fixer
-
-The fixer for `require-example` will add an empty `@example`, but it will still
-report a missing example description after this is added.
-
-<a name="user-content-require-example-options"></a>
-<a name="require-example-options"></a>
-## Options
-
-This rule has an object option.
-
-<a name="user-content-require-example-options-exemptedby"></a>
-<a name="require-example-options-exemptedby"></a>
-### <code>exemptedBy</code>
-
-Array of tags (e.g., `['type']`) whose presence on the document
-block avoids the need for an `@example`. Defaults to an array with
-`inheritdoc`. If you set this array, it will overwrite the default,
-so be sure to add back `inheritdoc` if you wish its presence to cause
-exemption of the rule.
-
-<a name="user-content-require-example-options-exemptnoarguments"></a>
-<a name="require-example-options-exemptnoarguments"></a>
-### <code>exemptNoArguments</code>
-
-Boolean to indicate that no-argument functions should not be reported for
-missing `@example` declarations.
-
-<a name="user-content-require-example-options-contexts"></a>
-<a name="require-example-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.
-(e.g., `ClassDeclaration` for ES6
-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"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
-section of our README for more on the expected format.
-
-<a name="user-content-require-example-options-checkconstructors"></a>
-<a name="require-example-options-checkconstructors"></a>
-### <code>checkConstructors</code>
-
-A value indicating whether `constructor`s should be checked.
-Defaults to `true`.
-
-<a name="user-content-require-example-options-checkgetters"></a>
-<a name="require-example-options-checkgetters"></a>
-### <code>checkGetters</code>
-
-A value indicating whether getters should be checked. Defaults to `false`.
-
-<a name="user-content-require-example-options-checksetters"></a>
-<a name="require-example-options-checksetters"></a>
-### <code>checkSetters</code>
-
-A value indicating whether setters should be checked. Defaults to `false`.
-
-<a name="user-content-require-example-options-enablefixer"></a>
-<a name="require-example-options-enablefixer"></a>
-### <code>enableFixer</code>
-
-A boolean on whether to enable the fixer (which adds an empty `@example` block).
-Defaults to `true`.
-
-<a name="user-content-require-example-context-and-settings"></a>
-<a name="require-example-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
-|Tags|`example`|
-|Recommended|false|
-|Options|`checkConstructors`, `checkGetters`, `checkSetters`, `contexts`, `enableFixer`, `exemptedBy`, `exemptNoArguments`|
-|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
-
-<a name="user-content-failing-examples"></a>
-<a name="failing-examples"></a>
-# Failing examples
-
-The following patterns are considered problems:
-
-````js
-/**
- *
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @example declaration.
-
-/**
- *
- */
-function quux (someParam) {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"exemptNoArguments":true}]
-// Message: Missing JSDoc @example declaration.
-
-/**
- *
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @example declaration.
-
-/**
- * @example
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @example description.
-
-/**
- * @constructor
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @example declaration.
-
-/**
- * @constructor
- * @example
- */
-function quux () {
-
-}
-// Message: Missing JSDoc @example description.
-
-/**
- *
- */
-class quux {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"contexts":["ClassDeclaration"]}]
-// Message: Missing JSDoc @example declaration.
-
-/**
- *
- */
-// "jsdoc/require-example": ["error"|"warn", {"contexts":["any"]}]
-// Message: Missing JSDoc @example declaration.
-
-/**
- *
- */
-function quux () {
-}
-// "jsdoc/require-example": ["error"|"warn", {"exemptedBy":["notPresent"]}]
-// Message: Missing JSDoc @example declaration.
-
-class TestClass {
-  /**
-   *
-   */
-  get Test() { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkGetters":true}]
-// Message: Missing JSDoc @example declaration.
-
-class TestClass {
-  /**
-   * @example
-   */
-  get Test() { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkGetters":true}]
-// Message: Missing JSDoc @example description.
-
-class TestClass {
-  /**
-   *
-   */
-  set Test(value) { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkSetters":true}]
-// Message: Missing JSDoc @example declaration.
-
-class TestClass {
-  /**
-   * @example
-   */
-  set Test(value) { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkSetters":true}]
-// Message: Missing JSDoc @example description.
-
-/**
- *
- */
-function quux (someParam) {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"enableFixer":true}]
-// Message: Missing JSDoc @example declaration.
-
-/**
- *
- */
-function quux (someParam) {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"enableFixer":false}]
-// Message: Missing JSDoc @example declaration.
-````
-
-
-
-<a name="user-content-failing-examples-passing-examples"></a>
-<a name="failing-examples-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- *
- */
-
-/**
- * @example
- * // arbitrary example content
- */
-function quux () {
-
-}
-
-/**
- * @example
- * quux(); // does something useful
- */
-function quux () {
-
-}
-
-/**
- * @example <caption>Valid usage</caption>
- * quux(); // does something useful
- *
- * @example <caption>Invalid usage</caption>
- * quux('random unwanted arg'); // results in an error
- */
-function quux () {
-
-}
-
-/**
- * @constructor
- */
-function quux () {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkConstructors":false}]
-
-/**
- * @constructor
- * @example
- */
-function quux () {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkConstructors":false}]
-
-class Foo {
-  /**
-   *
-   */
-  constructor () {
-
-  }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkConstructors":false}]
-
-/**
- * @inheritdoc
- */
-function quux () {
-
-}
-
-/**
- * @type {MyCallback}
- */
-function quux () {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"exemptedBy":["type"]}]
-
-/**
- * @example Some example code
- */
-class quux {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"contexts":["ClassDeclaration"]}]
-
-/**
- *
- */
-function quux () {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"contexts":["ClassDeclaration"]}]
-
-class TestClass {
-  /**
-   *
-   */
-  get Test() { }
-}
-
-class TestClass {
-  /**
-   * @example
-   */
-  get Test() { }
-}
-
-class TestClass {
-  /**
-   * @example Test
-   */
-  get Test() { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkGetters":true}]
-
-class TestClass {
-  /**
-   *
-   */
-  set Test(value) { }
-}
-
-class TestClass {
-  /**
-   * @example
-   */
-  set Test(value) { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkSetters":false}]
-
-class TestClass {
-  /**
-   * @example Test
-   */
-  set Test(value) { }
-}
-// "jsdoc/require-example": ["error"|"warn", {"checkSetters":true}]
-
-/**
- *
- */
-function quux () {
-
-}
-// "jsdoc/require-example": ["error"|"warn", {"exemptNoArguments":true}]
-````
-

package/docs/rules/require-file-overview.md

@@ -1,324 +0,0 @@
-<a name="user-content-require-file-overview"></a>
-<a name="require-file-overview"></a>
-# <code>require-file-overview</code>
-
-* [Options](#user-content-require-file-overview-options)
-    * [`tags`](#user-content-require-file-overview-options-tags)
-* [Context and settings](#user-content-require-file-overview-context-and-settings)
-* [Failing examples](#user-content-require-file-overview-failing-examples)
-* [Passing examples](#user-content-require-file-overview-passing-examples)
-
-
-Checks that:
-
-1. All files have a `@file`, `@fileoverview`, or `@overview` tag.
-2. Duplicate file overview tags within a given file will be reported
-3. File overview tags will be reported which are not, as per
-  [the docs](https://jsdoc.app/tags-file.html), "at the beginning of
-  the file"–where beginning of the file is interpreted in this rule
-  as being when the overview tag is not preceded by anything other than
-  a comment.
-
-<a name="user-content-require-file-overview-options"></a>
-<a name="require-file-overview-options"></a>
-## Options
-
-<a name="user-content-require-file-overview-options-tags"></a>
-<a name="require-file-overview-options-tags"></a>
-### <code>tags</code>
-
-The keys of this object are tag names, and the values are configuration
-objects indicating what will be checked for these whole-file tags.
-
-Each configuration object has the following boolean keys (which default
-to `false` when this option is supplied): `mustExist`, `preventDuplicates`,
-`initialCommentsOnly`. These correspond to the three items above.
-
-When no `tags` is present, the default is:
-
-```json
-{
-  "file": {
-    "initialCommentsOnly": true,
-    "mustExist": true,
-    "preventDuplicates": true,
-  }
-}
-```
-
-You can add additional tag names and/or override `file` if you supply this
-option, e.g., in place of or in addition to `file`, giving other potential
-file global tags like `@license`, `@copyright`, `@author`, `@module` or
-`@exports`, optionally restricting them to a single use or preventing them
-from being preceded by anything besides comments.
-
-For example:
-
-```js
-{
-  "license": {
-    "mustExist": true,
-    "preventDuplicates": true,
-  }
-}
-```
-
-This would require one and only one `@license` in the file, though because
-`initialCommentsOnly` is absent and defaults to `false`, the `@license`
-can be anywhere.
-
-In the case of `@license`, you can use this rule along with the
-`check-values` rule (with its `allowedLicenses` or `licensePattern` options),
-to enforce a license whitelist be present on every JS file.
-
-Note that if you choose to use `preventDuplicates` with `license`, you still
-have a way to allow multiple licenses for the whole page by using the SPDX
-"AND" expression, e.g., `@license (MIT AND GPL-3.0)`.
-
-Note that the tag names are the main jsdoc tag name, so you should use `file`
-in this configuration object regardless of whether you have configured
-`fileoverview` instead of `file` on `tagNamePreference` (i.e., `fileoverview`
-will be checked, but you must use `file` on the configuration object).
-
-<a name="user-content-require-file-overview-context-and-settings"></a>
-<a name="require-file-overview-context-and-settings"></a>
-## Context and settings
-
-|||
-|---|---|
-|Context|Everywhere|
-|Tags|`file`; others when `tags` set|
-|Aliases|`fileoverview`, `overview`|
-|Recommended|false|
-|Options|`tags`|
-
-<a name="user-content-require-file-overview-failing-examples"></a>
-<a name="require-file-overview-failing-examples"></a>
-## Failing examples
-
-The following patterns are considered problems:
-
-````js
-
-// Message: Missing @file
-
-
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"file":{"initialCommentsOnly":true,"mustExist":true,"preventDuplicates":true}}}]
-// Message: Missing @file
-
-
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"file":{"mustExist":true}}}]
-// Message: Missing @file
-
-
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"author":{"initialCommentsOnly":false,"mustExist":true,"preventDuplicates":false}}}]
-// Message: Missing @author
-
-/**
- *
- */
-// Message: Missing @file
-
-/**
- *
- */
-function quux () {}
-// Message: Missing @file
-
-/**
- *
- */
-function quux () {}
-// Settings: {"jsdoc":{"tagNamePreference":{"file":"fileoverview"}}}
-// Message: Missing @fileoverview
-
-/**
- *
- */
-function quux () {}
-// Settings: {"jsdoc":{"tagNamePreference":{"file":"overview"}}}
-// Message: Missing @overview
-
-/**
- *
- */
-function quux () {}
-// Settings: {"jsdoc":{"tagNamePreference":{"file":false}}}
-// Message: `settings.jsdoc.tagNamePreference` cannot block @file for the `require-file-overview` rule
-
-/**
- *
- */
-function quux () {}
-// Settings: {"jsdoc":{"tagNamePreference":{"file":false}}}
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"file":{"initialCommentsOnly":false,"mustExist":true,"preventDuplicates":false}}}]
-// Message: `settings.jsdoc.tagNamePreference` cannot block @file for the `require-file-overview` rule
-
-/**
- *
- */
-function quux () {}
-// Settings: {"jsdoc":{"tagNamePreference":{"file":{"message":"Don't use file"}}}}
-// Message: `settings.jsdoc.tagNamePreference` cannot block @file for the `require-file-overview` rule
-
-/**
- * @param a
- */
-function quux (a) {}
-// Message: Missing @file
-
-/**
- * @param a
- */
-function quux (a) {}
-
-/**
- * @param b
- */
-function bar (b) {}
-// Message: Missing @file
-
-/**
- * @file
- */
-
- /**
-  * @file
-  */
-// Message: Duplicate @file
-
-/**
- * @copyright
- */
-
- /**
-  * @copyright
-  */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"copyright":{"initialCommentsOnly":false,"mustExist":false,"preventDuplicates":true}}}]
-// Message: Duplicate @copyright
-
-function quux () {
-}
-/**
- * @file
- */
-// Message: @file should be at the beginning of the file
-
-function quux () {
-}
-/**
- * @license
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":true,"mustExist":false,"preventDuplicates":false}}}]
-// Message: @license should be at the beginning of the file
-
-function quux () {
-}
-/**
- * @license
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":true}}}]
-// Message: @license should be at the beginning of the file
-
-/**
- * @file
- */
-
-/**
- * @file
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"file":{"initialCommentsOnly":true,"preventDuplicates":true}}}]
-// Message: Duplicate @file
-
-/**
- *
- */
-function quux () {}
-// Settings: {"jsdoc":{"tagNamePreference":{"file":{"replacement":"fileoverview"}}}}
-// Message: Missing @fileoverview
-````
-
-
-
-<a name="user-content-require-file-overview-passing-examples"></a>
-<a name="require-file-overview-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * @file
- */
-
-/**
- * @file
- */
-
-/**
- * @file
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":true,"preventDuplicates":true}}}]
-
-// Ok preceded by comment
-/**
- * @file
- */
-
-/**
- * @fileoverview
- */
-// Settings: {"jsdoc":{"tagNamePreference":{"file":"fileoverview"}}}
-
-/**
- * @overview
- */
-// Settings: {"jsdoc":{"tagNamePreference":{"file":"overview"}}}
-
-/**
- * @file Description of file
- */
-
-/**
- * @file Description of file
- */
-function quux () {
-}
-
-/**
- *
- */
-
-function quux () {
-}
-/**
- *
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":true,"mustExist":false,"preventDuplicates":false}}}]
-
-function quux () {
-}
-/**
- *
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":false,"mustExist":false,"preventDuplicates":false}}}]
-
-function quux () {
-}
-/**
- *
- */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":false,"mustExist":false,"preventDuplicates":true}}}]
-
-/**
- * @license MIT
- */
-
- var a
-
- /**
-  * @type {Array}
-  */
-// "jsdoc/require-file-overview": ["error"|"warn", {"tags":{"license":{"initialCommentsOnly":true,"mustExist":false,"preventDuplicates":false}}}]
-````
-