eslint-plugin-jsdoc 58.1.1 → 59.0.0

package/src/rules/convertToJsdocComments.js

@@ -303,12 +303,24 @@ export default {
         additionalProperties: false,
         properties: {
           allowedPrefixes: {
+            description: `An array of prefixes to allow at the beginning of a comment.
+
+Defaults to \`['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']\`.
+
+Supplying your own value overrides the defaults.`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           contexts: {
+            description: `The contexts array which will be checked for preceding content.
+
+Can either be strings or an object with a \`context\` string and an optional, default \`false\` \`inlineCommentBlock\` boolean.
+
+Defaults to \`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`, \`TSDeclareFunction\`.
+`,
             items: {
               anyOf: [
                 {
@@ -331,6 +343,11 @@ export default {
             type: 'array',
           },
           contextsAfter: {
+            description: `The contexts array which will be checked for content on the same line after.
+
+Can either be strings or an object with a \`context\` string and an optional, default \`false\` \`inlineCommentBlock\` boolean.
+
+Defaults to an empty array.`,
             items: {
               anyOf: [
                 {
@@ -353,6 +370,12 @@ export default {
             type: 'array',
           },
           contextsBeforeAndAfter: {
+            description: `The contexts array which will be checked for content before and on the same
+line after.
+
+Can either be strings or an object with a \`context\` string and an optional, default \`false\` \`inlineCommentBlock\` boolean.
+
+Defaults to \`VariableDeclarator\`, \`TSPropertySignature\`, \`PropertyDefinition\`.`,
             items: {
               anyOf: [
                 {
@@ -375,15 +398,40 @@ export default {
             type: 'array',
           },
           enableFixer: {
+            description: 'Set to `false` to disable fixing.',
             type: 'boolean',
           },
           enforceJsdocLineStyle: {
+            description: `What policy to enforce on the conversion of non-JSDoc comments without
+line breaks. (Non-JSDoc (mulitline) comments with line breaks will always
+be converted to \`multi\` style JSDoc comments.)
+
+- \`multi\` - Convert to multi-line style
+\`\`\`js
+/**
+ * Some text
+ */
+\`\`\`
+- \`single\` - Convert to single-line style
+\`\`\`js
+/** Some text */
+\`\`\`
+
+Defaults to \`multi\`.
+`,
             enum: [
               'multi', 'single',
             ],
             type: 'string',
           },
           lineOrBlockStyle: {
+            description: `What style of comments to which to apply JSDoc conversion.
+
+- \`block\` - Applies to block-style comments (\`/* ... */\`)
+- \`line\` - Applies to line-style comments (\`// ...\`)
+- \`both\` - Applies to both block and line-style comments
+
+Defaults to \`both\`.`,
             enum: [
               'block', 'line', 'both',
             ],

package/src/rules/emptyTags.js

@@ -75,7 +75,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Expects specific tags to be empty of any content.',
+      description: 'Checks tags that are expected to be empty (e.g., `@abstract` or `@async`), reporting if they have content',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/empty-tags.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -84,6 +84,15 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           tags: {
+            description: `If you want additional tags to be checked for their descriptions, you may
+add them within this option.
+
+\`\`\`js
+{
+  'jsdoc/empty-tags': ['error', {tags: ['event']}]
+}
+\`\`\`
+`,
             items: {
               type: 'string',
             },

package/src/rules/implementsOnClasses.js

@@ -26,7 +26,7 @@ export default iterateJsdoc(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Reports an issue with any non-constructor function using `@implements`.',
+      description: 'Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.md#repos-sticky-header',
     },
     schema: [
@@ -34,6 +34,20 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           contexts: {
+            description: `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.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). 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"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
             items: {
               anyOf: [
                 {

package/src/rules/informativeDocs.js

@@ -156,6 +156,23 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           aliases: {
+            description: `The \`aliases\` option allows indicating words as synonyms (aliases) of each other.
+
+For example, with \`{ aliases: { emoji: ["smiley", "winkey"] } }\`, the following comment would be considered uninformative:
+
+\`\`\`js
+/** A smiley/winkey. */
+let emoji;
+\`\`\`
+
+The default \`aliases\` option is:
+
+\`\`\`json
+{
+  "a": ["an", "our"]
+}
+\`\`\`
+`,
             patternProperties: {
               '.*': {
                 items: {
@@ -166,12 +183,40 @@ export default iterateJsdoc(({
             },
           },
           excludedTags: {
+            description: `Tags that should not be checked for valid contents.
+
+For example, with \`{ excludedTags: ["category"] }\`, the following comment would not be considered uninformative:
+
+\`\`\`js
+/** @category Types */
+function computeTypes(node) {
+  // ...
+}
+\`\`\`
+
+No tags are excluded by default.
+`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           uselessWords: {
+            description: `Words that are ignored when searching for one that adds meaning.
+
+For example, with \`{ uselessWords: ["our"] }\`, the following comment would be considered uninformative:
+
+\`\`\`js
+/** Our text. */
+let text;
+\`\`\`
+
+The default \`uselessWords\` option is:
+
+\`\`\`json
+["a", "an", "i", "in", "of", "s", "the"]
+\`\`\`
+`,
             items: {
               type: 'string',
             },

package/src/rules/linesBeforeBlock.js

@@ -108,21 +108,35 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           checkBlockStarts: {
+            description: `Whether to additionally check the start of blocks, such as classes or functions.
+Defaults to \`false\`.
+`,
             type: 'boolean',
           },
           excludedTags: {
+            description: `An array of tags whose presence in the JSDoc block will prevent the
+application of the rule. Defaults to \`['type']\` (i.e., if \`@type\` is present,
+lines before the block will not be added).
+`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           ignoreSameLine: {
+            description: `This option excludes cases where the JSDoc block occurs on the same line as a
+preceding code or comment. Defaults to \`true\`.
+`,
             type: 'boolean',
           },
           ignoreSingleLines: {
+            description: `This option excludes cases where the JSDoc block is only one line long.
+Defaults to \`true\`.
+`,
             type: 'boolean',
           },
           lines: {
+            description: 'The minimum number of lines to require. Defaults to 1.',
             type: 'integer',
           },
         },

package/src/rules/matchDescription.js

@@ -173,6 +173,19 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           contexts: {
+            description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied (e.g.,
+\`ClassDeclaration\` for ES6 classes).
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want the rule to apply to any
+JSDoc block throughout your files.
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.
+`,
             items: {
               anyOf: [
                 {
@@ -195,6 +208,42 @@ export default iterateJsdoc(({
             type: 'array',
           },
           mainDescription: {
+            description: `If you wish to override the main block description without changing the
+default \`match-description\` (which can cascade to the \`tags\` with \`true\`),
+you may use \`mainDescription\`:
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {
+    mainDescription: '[A-Z].*\\\\.',
+    tags: {
+      param: true,
+      returns: true
+    }
+  }]
+}
+\`\`\`
+
+There is no need to add \`mainDescription: true\`, as by default, the main
+block description (and only the main block description) is linted, though you
+may disable checking it by setting it to \`false\`.
+
+You may also provide an object with \`message\`:
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {
+    mainDescription: {
+      message: 'Capitalize first word of JSDoc block descriptions',
+      match: '[A-Z].*\\\\.'
+    },
+    tags: {
+      param: true,
+      returns: true
+    }
+  }]
+}
+\`\`\``,
             oneOf: [
               {
                 format: 'regex',
@@ -226,16 +275,96 @@ export default iterateJsdoc(({
             ],
           },
           matchDescription: {
+            description: `You can supply your own expression to override the default, passing a
+\`matchDescription\` string on the options object.
+
+Defaults to using (only) the \`v\` flag, so
+to add your own flags, encapsulate your expression as a string, but like a
+literal, e.g., \`/[A-Z].*\\./vi\`.
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {matchDescription: '[A-Z].*\\\\.'}]
+}
+\`\`\``,
             format: 'regex',
             type: 'string',
           },
           message: {
+            description: `You may provide a custom default message by using the following format:
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {
+    message: 'The default description should begin with a capital letter.'
+  }]
+}
+\`\`\`
+
+This can be overridden per tag or for the main block description by setting
+\`message\` within \`tags\` or \`mainDescription\`, respectively.
+`,
             type: 'string',
           },
           nonemptyTags: {
+            description: `If not set to \`false\`, will enforce that the following tags have at least
+some content:
+
+- \`@copyright\`
+- \`@example\`
+- \`@see\`
+- \`@todo\`
+
+If you supply your own tag description for any of the above tags in \`tags\`,
+your description will take precedence.`,
             type: 'boolean',
           },
           tags: {
+            description: `If you want different regular expressions to apply to tags, you may use
+the \`tags\` option object:
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    param: '\\\\- [A-Z].*\\\\.',
+    returns: '[A-Z].*\\\\.'
+  }}]
+}
+\`\`\`
+
+In place of a string, you can also add \`true\` to indicate that a particular
+tag should be linted with the \`matchDescription\` value (or the default).
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    param: true,
+    returns: true
+  }}]
+}
+\`\`\`
+
+Alternatively, you may supply an object with a \`message\` property to indicate
+the error message for that tag.
+
+\`\`\`js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    param: {message: 'Begin with a hyphen', match: '\\\\- [A-Z].*\\\\.'},
+    returns: {message: 'Capitalize for returns (the default)', match: true}
+  }}]
+}
+\`\`\`
+
+The tags \`@param\`/\`@arg\`/\`@argument\` and \`@property\`/\`@prop\` will be properly
+parsed to ensure that the matched "description" text includes only the text
+after the name.
+
+All other tags will treat the text following the tag name, a space, and
+an optional curly-bracketed type expression (and another space) as part of
+its "description" (e.g., for \`@returns {someType} some description\`, the
+description is \`some description\` while for \`@some-tag xyz\`, the description
+is \`xyz\`).`,
             patternProperties: {
               '.*': {
                 oneOf: [

package/src/rules/matchName.js

@@ -106,28 +106,58 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           match: {
+            description: `\`match\` is a required option containing an array of objects which determine
+the conditions whereby a name is reported as being problematic.
+
+These objects can have any combination of the following groups of optional
+properties, all of which act to confine one another.
+
+Note that \`comment\`, even if targeting a specific tag, is used to match the
+whole block. So if a \`comment\` finds its specific tag, it may still apply
+fixes found by the likes of \`disallowName\` even when a different tag has the
+disallowed name. An alternative is to ensure that \`comment\` finds the specific
+tag of the desired tag and/or name and no \`disallowName\` (or \`allowName\`) is
+supplied. In such a case, only one error will be reported, but no fixer will
+be applied, however.
+`,
             items: {
               additionalProperties: false,
               properties: {
                 allowName: {
+                  description: `Indicates which names are allowed for the given tag (or \`*\`).
+Accepts a string regular expression (optionally wrapped between two
+\`/\` delimiters followed by optional flags) used to match the name.`,
                   type: 'string',
                 },
                 comment: {
+                  description: 'As with `context` but AST for the JSDoc block comment and types.',
                   type: 'string',
                 },
                 context: {
+                  description: `AST to confine the allowing or disallowing to JSDoc blocks
+associated with a particular context. See the
+["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
                   type: 'string',
                 },
                 disallowName: {
+                  description: 'As with `allowName` but indicates names that are not allowed.',
                   type: 'string',
                 },
                 message: {
+                  description: 'An optional custom message to use when there is a match.',
                   type: 'string',
                 },
                 replacement: {
+                  description: `If \`disallowName\` is supplied and this value is present, it
+will replace the matched \`disallowName\` text.`,
                   type: 'string',
                 },
                 tags: {
+                  description: `This array should include tag names or \`*\` to indicate the
+  match will apply for all tags (except as confined by any context
+  properties). If \`*\` is not used, then these rules will only apply to
+  the specified tags. If \`tags\` is omitted, then \`*\` is assumed.`,
                   items: {
                     type: 'string',
                   },

package/src/rules/multilineBlocks.js

@@ -331,7 +331,7 @@ export default iterateJsdoc(({
       }).length)
     ) {
       utils.reportJSDoc(
-        'Multiline jsdoc blocks are prohibited by ' +
+        'Multiline JSDoc blocks are prohibited by ' +
           'your configuration but fixing would result in a single ' +
           'line block which you have prohibited with `noSingleLineBlocks`.',
       );
@@ -342,7 +342,7 @@ export default iterateJsdoc(({
     if (jsdoc.tags.length > 1) {
       if (!allowMultipleTags) {
         utils.reportJSDoc(
-          'Multiline jsdoc blocks are prohibited by ' +
+          'Multiline JSDoc blocks are prohibited by ' +
             'your configuration but the block has multiple tags.',
         );
 
@@ -351,7 +351,7 @@ export default iterateJsdoc(({
     } else if (jsdoc.tags.length === 1 && jsdoc.description.trim()) {
       if (!allowMultipleTags) {
         utils.reportJSDoc(
-          'Multiline jsdoc blocks are prohibited by ' +
+          'Multiline JSDoc blocks are prohibited by ' +
             'your configuration but the block has a description with a tag.',
         );
 
@@ -419,7 +419,7 @@ export default iterateJsdoc(({
       };
 
       utils.reportJSDoc(
-        'Multiline jsdoc blocks are prohibited by ' +
+        'Multiline JSDoc blocks are prohibited by ' +
           'your configuration.',
         null,
         fixer,
@@ -434,7 +434,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks.',
+      description: 'Controls how and whether JSDoc blocks can be expressed as single or multiple line blocks.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/multiline-blocks.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -443,9 +443,28 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           allowMultipleTags: {
+            description: `If \`noMultilineBlocks\` is set to \`true\` with this option and multiple tags are
+found in a block, an error will not be reported.
+
+Since multiple-tagged lines cannot be collapsed into a single line, this option
+prevents them from being reported. Set to \`false\` if you really want to report
+any blocks.
+
+This option will also be applied when there is a block description and a single
+tag (since a description cannot precede a tag on a single line, and also
+cannot be reliably added after the tag either).
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           minimumLengthForMultiline: {
+            description: `If \`noMultilineBlocks\` is set with this numeric option, multiline blocks will
+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.
+
+Defaults to not being in effect.`,
             type: 'integer',
           },
           multilineTags: {
@@ -462,23 +481,76 @@ export default iterateJsdoc(({
                 type: 'array',
               },
             ],
+            description: `If \`noMultilineBlocks\` is set with this option, multiline blocks may be allowed
+regardless of length as long as a tag or a tag of a certain type is present.
+
+If \`*\` is included in the array, the presence of a tags will allow for
+multiline blocks (but not when without any tags unless the amount of text is
+over an amount specified by \`minimumLengthForMultiline\`).
+
+If the array does not include \`*\` but lists certain tags, the presence of
+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.
+
+Defaults to \`['*']\`.
+`,
           },
           noFinalLineText: {
+            description: `For multiline blocks, any non-whitespace text preceding the \`*/\` on the final
+line will be reported. (Text preceding a newline is not reported.)
+
+\`noMultilineBlocks\` will have priority over this rule if it applies.
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           noMultilineBlocks: {
+            description: `Requires that JSDoc blocks are restricted to single lines only unless impacted
+by the options \`minimumLengthForMultiline\`, \`multilineTags\`, or
+\`allowMultipleTags\`.
+
+Defaults to \`false\`.`,
             type: 'boolean',
           },
           noSingleLineBlocks: {
+            description: `If this is \`true\`, any single line blocks will be reported, except those which
+are whitelisted in \`singleLineTags\`.
+
+Defaults to \`false\`.
+`,
             type: 'boolean',
           },
           noZeroLineText: {
+            description: `For multiline blocks, any non-whitespace text immediately after the \`/**\` and
+space will be reported. (Text after a newline is not reported.)
+
+\`noMultilineBlocks\` will have priority over this rule if it applies.
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           requireSingleLineUnderCount: {
+            description: `If this number is set, it indicates a minimum line width for a single line of
+JSDoc content spread over a multi-line comment block. If a single line is under
+the minimum length, it will be reported so as to enforce single line JSDoc blocks
+for such cases. Blocks are not reported which have multi-line descriptions,
+multiple tags, a block description and tag, or tags with multi-line types or
+descriptions.
+
+Defaults to \`null\`.
+`,
             type: 'number',
           },
           singleLineTags: {
+            description: `An array of tags which can nevertheless be allowed as single line blocks when
+\`noSingleLineBlocks\` is set.  You may set this to a empty array to
+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).
+
+Defaults to \`['lends', 'type']\`.`,
             items: {
               type: 'string',
             },

package/src/rules/noBadBlocks.js

@@ -3,7 +3,7 @@ import {
   parse as commentParser,
 } from 'comment-parser';
 
-// Neither a single nor 3+ asterisks are valid jsdoc per
+// Neither a single nor 3+ asterisks are valid JSDoc per
 //  https://jsdoc.app/about-getting-started.html#adding-documentation-comments-to-your-code
 const commentRegexp = /^\/\*(?!\*)/v;
 const extraAsteriskCommentRegexp = /^\/\*{3,}/v;
@@ -93,7 +93,7 @@ export default iterateJsdoc(({
   checkFile: true,
   meta: {
     docs: {
-      description: 'This rule checks for multi-line-style comments which fail to meet the criteria of a jsdoc block.',
+      description: 'This rule checks for multi-line-style comments which fail to meet the criteria of a JSDoc block.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-bad-blocks.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -102,12 +102,21 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           ignore: {
+            description: `An array of directives that will not be reported if present at the beginning of
+a multi-comment block and at-sign \`/* @\`.
+
+Defaults to \`['ts-check', 'ts-expect-error', 'ts-ignore', 'ts-nocheck']\`
+(some directives [used by TypeScript](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check)).
+`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           preventAllMultiAsteriskBlocks: {
+            description: `A boolean (defaulting to \`false\`) which if \`true\` will prevent all
+JSDoc-like blocks with more than two initial asterisks even those without
+apparent tag content.`,
             type: 'boolean',
           },
         },

package/src/rules/noBlankBlockDescriptions.js

@@ -59,7 +59,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Detects and removes extra lines of a blank block description',
+      description: 'If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-block-descriptions.md#repos-sticky-header',
     },
     fixable: 'whitespace',

package/src/rules/noBlankBlocks.js

@@ -43,9 +43,11 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           enableFixer: {
+            description: 'Whether or not to auto-remove the blank block. Defaults to `false`.',
             type: 'boolean',
           },
         },
+        type: 'object',
       },
     ],
     type: 'suggestion',