eslint-plugin-jsdoc 36.0.8 → 37.0.1

package/README.md

@@ -18,7 +18,7 @@ JSDoc linting rules for ESLint.
         * [`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` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
+        * [`@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)
@@ -250,10 +250,8 @@ how many line breaks to add when a block is missing.
     types/namepaths (Closure allows types on some tags which the others do not,
     so these tags will additionally be checked in "closure" mode)
   - For type-checking rules, impacts parsing of types (through
-    [jsdoctypeparser](https://github.com/jsdoctypeparser/jsdoctypeparser)
-    dependency); note that some TypeScript features are
-    [not yet](https://github.com/gajus/eslint-plugin-jsdoc/issues/145)
-    [supported](https://github.com/jsdoctypeparser/jsdoctypeparser/issues/50)
+    [jsdoc-type-pratt-parser](https://github.com/simonseyock/jsdoc-type-pratt-parser)
+    dependency)
   - Check preferred tag names
   - Disallows namepath on `@interface` for "closure" mode in `valid-types` (and
       avoids checking in other rules)
@@ -389,14 +387,15 @@ This setting is utilized by the the rule for tag name checking
 - `require-returns-description`
 - `require-returns-type`
 
-<a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns"></a>
-### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>
+<a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields"></a>
+### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code>/<code>@ignore</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>/<code>@throws</code>/<code>@yields</code>
 
 The following settings allows the element(s) they reference to be omitted
 on the JSDoc comment block of the function or that of its parent class
 for any of the "require" rules (i.e., `require-param`, `require-description`,
-`require-example`, or `require-returns`).
+`require-example`, `require-returns`, `require-throws`, `require-yields`).
 
+* `settings.jsdoc.ignoreReplacesDocs` (`@ignore`) - Defaults to `true`
 * `settings.jsdoc.overrideReplacesDocs` (`@override`) - Defaults to `true`
 * `settings.jsdoc.augmentsExtendsReplacesDocs` (`@augments` or its alias
     `@extends`) - Defaults to `false`.
@@ -409,6 +408,7 @@ The format of the configuration is as follows:
     "rules": {},
     "settings": {
         "jsdoc": {
+            "ignoreReplacesDocs": true,
             "overrideReplacesDocs": true,
             "augmentsExtendsReplacesDocs": true,
             "implementsReplacesDocs": true
@@ -577,7 +577,7 @@ properties:
     declaration of the function expression for
     `const quux = function () {}`, the associated comment would,
     in both cases, generally be expected to be on the line above both, rather
-    than to be immediately preceding the funciton (in the case of the
+    than to be immediately preceding the function (in the case of the
     function). See [@es-joy/jsdoccomment](https://github.com/es-joy/jsdoccomment)
     for the precise structure of the comment (and comment type) nodes.
 
@@ -945,6 +945,9 @@ function quux (foo) {
 <a name="eslint-plugin-jsdoc-rules-check-examples"></a>
 ### <code>check-examples</code>
 
+> **NOTE**: This rule currently does not work in ESLint 8 (we are waiting for
+> [issue 14745](https://github.com/eslint/eslint/issues/14745)).
+
 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.
@@ -1932,6 +1935,20 @@ function quux () {
 * ```
 */
 // "jsdoc/check-indentation": ["error"|"warn", {"excludeTags":[]}]
+
+/**
+ * @example
+ * ```
+ * @MyDecorator({
+ *   myOptions: 42
+ * })
+ * export class MyClass {}
+ * ```
+ */
+function MyDecorator(options: { myOptions: number }) {
+  return (Base: Function) => {};
+}
+// "jsdoc/check-indentation": ["error"|"warn", {"excludeTags":["example","MyDecorator"]}]
 ````
 
 
@@ -4751,7 +4768,7 @@ behavior.
 See also the documentation on `settings.jsdoc.preferredTypes` which impacts
 the behavior of `check-types`.
 
-Note that if there is an error [parsing](https://github.com/jsdoctypeparser/jsdoctypeparser)
+Note that if there is an error [parsing](https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser)
 types for a tag, the function will silently ignore that tag, leaving it to
 the `valid-types` rule to report parsing errors.
 
@@ -5737,7 +5754,7 @@ If present as an array, will be used in place of SPDX identifiers.
 A string to be converted into a `RegExp` (with `u` flag) and whose first
 parenthetical grouping, if present, will match the portion of the license
 description to check (if no grouping is present, then the whole portion
-matched will be used). Defaults to `/([^\n]*)/gu`, i.e., the SPDX expression
+matched will be used). Defaults to `/([^\n\r]*)/gu`, i.e., the SPDX expression
 is expected before any line breaks.
 
 Note that the `/` delimiters are optional, but necessary to add flags.
@@ -5999,6 +6016,12 @@ function quux (foo) {
 function quux (foo) {
 
 }
+
+/**
+ * @module test
+ * @license MIT
+ */
+'use strict';
 ````
 
 
@@ -6894,7 +6917,7 @@ class MyClass {
    */
   myClassField = 1
 }
-// "jsdoc/match-description": ["error"|"warn", {"contexts":["ClassProperty"]}]
+// "jsdoc/match-description": ["error"|"warn", {"contexts":["PropertyDefinition"]}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
 /**
@@ -7162,7 +7185,7 @@ class MyClass {
    */
   myClassField = 1
 }
-// "jsdoc/match-description": ["error"|"warn", {"contexts":["ClassProperty"]}]
+// "jsdoc/match-description": ["error"|"warn", {"contexts":["PropertyDefinition"]}]
 
 /**
  * Foo.
@@ -7341,7 +7364,7 @@ be applied, however.
 |||
 |---|---|
 |Context|everywhere|
-|Tags|(The tags specifie by `tags`, including any tag if `*` is set)|
+|Tags|(The tags specified by `tags`, including any tag if `*` is set)|
 |Recommended|false|
 |Settings|`structuredTags`|
 |Options|`match`|
@@ -9147,7 +9170,7 @@ The following types are always considered defined.
 Note that preferred types indicated within `settings.jsdoc.preferredTypes` will
 also be assumed to be defined.
 
-Also note that if there is an error [parsing](https://github.com/jsdoctypeparser/jsdoctypeparser)
+Also note that if there is an error [parsing](https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser)
 types for a tag, the function will silently ignore that tag, leaving it to
 the `valid-types` rule to report parsing errors.
 
@@ -10741,7 +10764,7 @@ An options object may have any of the following properties:
 | Aliases  | `desc`                                                                                                        |
 | Recommended | false |
 | Options  | `contexts`, `exemptedBy`, `descriptionStyle`, `checkConstructors`, `checkGetters`, `checkSetters`             |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
 
 The following patterns are considered problems:
 
@@ -11320,7 +11343,7 @@ report a missing example description after this is added.
 |Tags|`example`|
 |Recommended|false|
 |Options|`exemptedBy`, `exemptNoArguments`, `avoidExampleOnConstructors`, `contexts`|
-|Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
+|Settings|`ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 The following patterns are considered problems:
 
@@ -12793,7 +12816,7 @@ class Animal {
   @SomeAnnotation('optionalParameter')
   tail: boolean;
 }
-// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ClassProperty"]}]
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["PropertyDefinition"]}]
 // Message: Missing JSDoc comment.
 
 @Entity('users')
@@ -12887,7 +12910,7 @@ export class MyComponentComponent {
   @Input()
   public value = new EventEmitter();
 }
-// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ClassProperty:has(Decorator[expression.callee.name=\"Input\"])"]}]
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["PropertyDefinition > Decorator[expression.callee.name=\"Input\"]"]}]
 // Message: Missing JSDoc comment.
 
 requestAnimationFrame(draw)
@@ -12931,6 +12954,12 @@ function comment () {
 }
 // "jsdoc/require-jsdoc": ["error"|"warn", {"enableFixer":false,"fixerMessage":" TODO: add comment"}]
 // Message: Missing JSDoc comment.
+
+export class InovaAutoCompleteComponent {
+  public disabled = false;
+}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["PropertyDefinition"],"publicOnly":true}]
+// Message: Missing JSDoc comment.
 ````
 
 The following patterns are not considered problems:
@@ -12958,7 +12987,7 @@ export class Foo {
 // "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSInterfaceDeclaration","TSMethodSignature","TSPropertySignature"],"publicOnly":{"ancestorsOnly":true}}]
 
 /** This is comment */
-function someFunciton() {
+function someFunction() {
   interface FooBar {
     fooBar: string;
   }
@@ -14525,7 +14554,7 @@ supplied as default values. Defaults to `false`.
 | Aliases  | `arg`, `argument` |
 |Recommended | true|
 | Options  | `autoIncrementBase`, `checkDestructured`, `checkDestructuredRoots`, `contexts`, `enableFixer`, `enableRootFixer`, `enableRestElementFixer`, `checkRestProperty`, `exemptedBy`, `checkConstructors`, `checkGetters`, `checkSetters`, `checkTypesPattern`, `unnamedRootBase`, `useDefaultObjectProperties`|
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 The following patterns are considered problems:
 
@@ -14717,6 +14746,15 @@ function quux (foo) {
 // Settings: {"jsdoc":{"overrideReplacesDocs":false}}
 // Message: Missing JSDoc @param "foo" declaration.
 
+/**
+ * @ignore
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":false}}
+// Message: Missing JSDoc @param "foo" declaration.
+
 /**
  * @implements
  */
@@ -14756,6 +14794,20 @@ class A {
 // Settings: {"jsdoc":{"overrideReplacesDocs":false}}
 // Message: Missing JSDoc @param "foo" declaration.
 
+/**
+ * @ignore
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":false}}
+// Message: Missing JSDoc @param "foo" declaration.
+
 /**
  * @implements
  */
@@ -15296,6 +15348,14 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"overrideReplacesDocs":true}}
 
+/**
+ * @ignore
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":true}}
+
 /**
  * @implements
  */
@@ -15404,6 +15464,19 @@ class A {
 }
 // Settings: {"jsdoc":{"overrideReplacesDocs":true}}
 
+/**
+ * @ignore
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"ignoreReplacesDocs":true}}
+
 /**
  * @implements
  */
@@ -17005,7 +17078,7 @@ Will also report if multiple `@returns` tags are present.
 | Aliases  | `return` |
 |Recommended|true|
 | Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 
@@ -18049,7 +18122,7 @@ Requires that throw statements are documented.
 | Aliases  | `exception` |
 |Recommended|true|
 | Options  | `contexts`, `exemptedBy` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 
@@ -18359,7 +18432,7 @@ option to expect a non-standard `@next` tag.
 |Aliases|`yield`|
 |Recommended|true|
 | Options  | `contexts`,  `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 
@@ -19934,10 +20007,10 @@ The following patterns are not considered problems:
 
 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, [jsdoctypeparser](https://github.com/jsdoctypeparser/jsdoctypeparser),
+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
-determine whether to use jsdoctypeparser's "permissive" mode or the stricter
-"jsdoc", "typescript", "closure" modes.
+determine whether to use jsdoc-type-pratt-parser's "permissive" parsing or
+the stricter "jsdoc", "typescript", "closure" modes.
 
 The following tags have their "type" portions (the segment within brackets)
 checked (though those portions may sometimes be confined to namepaths,

package/dist/iterateJsdoc.js

@@ -4,13 +4,13 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = iterateJsdoc;
+exports.getSettings = void 0;
 Object.defineProperty(exports, "parseComment", {
   enumerable: true,
   get: function () {
     return _jsdoccomment.parseComment;
   }
 });
-exports.getSettings = void 0;
 
 var _jsdoccomment = require("@es-joy/jsdoccomment");
 
@@ -87,6 +87,7 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
   const {
     tagNamePreference,
     overrideReplacesDocs,
+    ignoreReplacesDocs,
     implementsReplacesDocs,
     augmentsExtendsReplacesDocs,
     maxLines,
@@ -476,7 +477,7 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
   utils.avoidDocs = () => {
     var _context$options$0$ex, _context$options$;
 
-    if (overrideReplacesDocs !== false && (utils.hasTag('override') || utils.classHasTag('override')) || implementsReplacesDocs !== false && (utils.hasTag('implements') || utils.classHasTag('implements')) || augmentsExtendsReplacesDocs && (utils.hasATag(['augments', 'extends']) || utils.classHasTag('augments') || utils.classHasTag('extends'))) {
+    if (ignoreReplacesDocs !== false && (utils.hasTag('ignore') || utils.classHasTag('ignore')) || overrideReplacesDocs !== false && (utils.hasTag('override') || utils.classHasTag('override')) || implementsReplacesDocs !== false && (utils.hasTag('implements') || utils.classHasTag('implements')) || augmentsExtendsReplacesDocs && (utils.hasATag(['augments', 'extends']) || utils.classHasTag('augments') || utils.classHasTag('extends'))) {
       return true;
     }
 
@@ -651,9 +652,9 @@ const getUtils = (node, jsdoc, jsdocNode, settings, report, context, iteratingAl
 };
 
 const getSettings = context => {
-  var _context$settings$jsd, _context$settings$jsd2, _context$settings$jsd3, _context$settings$jsd4, _context$settings$jsd5, _context$settings$jsd6, _context$settings$jsd7, _context$settings$jsd8, _context$settings$jsd9, _context$settings$jsd10, _context$settings$jsd11, _context$settings$jsd12, _context$settings$jsd13, _context$settings$jsd14, _context$settings$jsd15, _context$settings$jsd16, _context$settings$jsd17;
+  var _context$settings$jsd, _context$settings$jsd2, _context$settings$jsd3, _context$settings$jsd4, _context$settings$jsd5, _context$settings$jsd6, _context$settings$jsd7, _context$settings$jsd8, _context$settings$jsd9, _context$settings$jsd10, _context$settings$jsd11, _context$settings$jsd12, _context$settings$jsd13, _context$settings$jsd14, _context$settings$jsd15, _context$settings$jsd16, _context$settings$jsd17, _context$settings$jsd18;
 
-  /* eslint-disable sort-keys-fix/sort-keys-fix */
+  /* eslint-disable canonical/sort-keys */
   const settings = {
     // All rules
     ignorePrivate: Boolean((_context$settings$jsd = context.settings.jsdoc) === null || _context$settings$jsd === void 0 ? void 0 : _context$settings$jsd.ignorePrivate),
@@ -666,14 +667,16 @@ const getSettings = context => {
     preferredTypes: (_context$settings$jsd9 = (_context$settings$jsd10 = context.settings.jsdoc) === null || _context$settings$jsd10 === void 0 ? void 0 : _context$settings$jsd10.preferredTypes) !== null && _context$settings$jsd9 !== void 0 ? _context$settings$jsd9 : {},
     // `check-types`, `no-undefined-types`, `valid-types`
     structuredTags: (_context$settings$jsd11 = (_context$settings$jsd12 = context.settings.jsdoc) === null || _context$settings$jsd12 === void 0 ? void 0 : _context$settings$jsd12.structuredTags) !== null && _context$settings$jsd11 !== void 0 ? _context$settings$jsd11 : {},
-    // `require-param`, `require-description`, `require-example`, `require-returns`
+    // `require-param`, `require-description`, `require-example`,
+    // `require-returns`, `require-throw`, `require-yields`
     overrideReplacesDocs: (_context$settings$jsd13 = context.settings.jsdoc) === null || _context$settings$jsd13 === void 0 ? void 0 : _context$settings$jsd13.overrideReplacesDocs,
-    implementsReplacesDocs: (_context$settings$jsd14 = context.settings.jsdoc) === null || _context$settings$jsd14 === void 0 ? void 0 : _context$settings$jsd14.implementsReplacesDocs,
-    augmentsExtendsReplacesDocs: (_context$settings$jsd15 = context.settings.jsdoc) === null || _context$settings$jsd15 === void 0 ? void 0 : _context$settings$jsd15.augmentsExtendsReplacesDocs,
+    ignoreReplacesDocs: (_context$settings$jsd14 = context.settings.jsdoc) === null || _context$settings$jsd14 === void 0 ? void 0 : _context$settings$jsd14.ignoreReplacesDocs,
+    implementsReplacesDocs: (_context$settings$jsd15 = context.settings.jsdoc) === null || _context$settings$jsd15 === void 0 ? void 0 : _context$settings$jsd15.implementsReplacesDocs,
+    augmentsExtendsReplacesDocs: (_context$settings$jsd16 = context.settings.jsdoc) === null || _context$settings$jsd16 === void 0 ? void 0 : _context$settings$jsd16.augmentsExtendsReplacesDocs,
     // Many rules, e.g., `check-tag-names`
-    mode: (_context$settings$jsd16 = (_context$settings$jsd17 = context.settings.jsdoc) === null || _context$settings$jsd17 === void 0 ? void 0 : _context$settings$jsd17.mode) !== null && _context$settings$jsd16 !== void 0 ? _context$settings$jsd16 : context.parserPath.includes('@typescript-eslint') ? 'typescript' : 'jsdoc'
+    mode: (_context$settings$jsd17 = (_context$settings$jsd18 = context.settings.jsdoc) === null || _context$settings$jsd18 === void 0 ? void 0 : _context$settings$jsd18.mode) !== null && _context$settings$jsd17 !== void 0 ? _context$settings$jsd17 : context.parserPath.includes('@typescript-eslint') ? 'typescript' : 'jsdoc'
   };
-  /* eslint-enable sort-keys-fix/sort-keys-fix */
+  /* eslint-enable canonical/sort-keys */
 
   _jsdocUtils.default.setTagStructure(settings.mode);
 
@@ -721,7 +724,8 @@ const makeReport = (context, commentNode) => {
         start: {
           line: lineNumber
         }
-      };
+      }; // Todo: Remove ignore once `check-examples` can be restored for ESLint 8+
+      // istanbul ignore if
 
       if (jsdocLoc.column) {
         const colNumber = commentNode.loc.start.column + jsdocLoc.column;
@@ -824,7 +828,7 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveContexts) => {
     } = sourceCode;
     const utils = getBasicUtils(context, settings);
     jsdocNodes.forEach(jsdocNode => {
-      if (!/^\/\*\*\s/.test(sourceCode.getText(jsdocNode))) {
+      if (!/^\/\*\*\s/u.test(sourceCode.getText(jsdocNode))) {
         return;
       }