eslint-plugin-jsdoc 58.1.1 → 59.0.0

package/src/rules/noDefaults.js

@@ -52,6 +52,20 @@ 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.
+
+\`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: [
                 {
@@ -74,6 +88,11 @@ export default iterateJsdoc(({
             type: 'array',
           },
           noOptionalParamNames: {
+            description: `Set this to \`true\` to report the presence of optional parameters. May be
+used if the project is insisting on optionality being indicated by
+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).`,
             type: 'boolean',
           },
         },

package/src/rules/noMissingSyntax.js

@@ -101,7 +101,7 @@ export default iterateJsdoc(({
     // Report when MISSING
     contexts.some((cntxt) => {
       const contextStr = typeof cntxt === 'object' ? cntxt.context ?? 'any' : cntxt;
-      const comment = typeof cntxt === 'string' ? '' : cntxt?.comment;
+      const comment = typeof cntxt === 'string' ? '' : cntxt?.comment ?? '';
 
       const contextKey = contextStr === 'any' ? 'undefined' : contextStr;
 
@@ -153,12 +153,32 @@ export default iterateJsdoc(({
       description: 'Reports when certain comment structures are always expected.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-missing-syntax.md#repos-sticky-header',
     },
-    fixable: 'code',
     schema: [
       {
         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.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+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. Defaults to
+\`"Syntax is required: {{context}}"\`, or with a comment, to
+\`"Syntax is required: {{context}} with {{comment}}"\`.
+
+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/noMultiAsterisks.js

@@ -116,12 +116,41 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           allowWhitespace: {
+            description: `Set to \`true\` if you wish to allow asterisks after a space (as with Markdown):
+
+\`\`\`js
+/**
+ * *bold* text
+ */
+\`\`\`
+
+Defaults to \`false\`.`,
             type: 'boolean',
           },
           preventAtEnd: {
+            description: `Prevent the likes of this:
+
+\`\`\`js
+/**
+ *
+ *
+ **/
+\`\`\`
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           preventAtMiddleLines: {
+            description: `Prevent the likes of this:
+
+\`\`\`js
+/**
+ *
+ **
+ */
+\`\`\`
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
         },

package/src/rules/noRestrictedSyntax.js

@@ -48,12 +48,28 @@ export default iterateJsdoc(({
       description: 'Reports when certain comment structures are present.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-restricted-syntax.md#repos-sticky-header',
     },
-    fixable: 'code',
     schema: [
       {
         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.
+
+Use the \`message\` property to indicate the specific error to be shown when an
+error is reported for that context being found. Defaults to
+\`"Syntax is restricted: {{context}}"\`, or with a comment, to
+\`"Syntax is restricted: {{context}} with {{comment}}"\`.
+
+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/noTypes.js

@@ -54,7 +54,7 @@ export default iterateJsdoc(({
   ],
   meta: {
     docs: {
-      description: 'This rule reports types being used on `@param` or `@returns`.',
+      description: 'This rule reports types being used on `@param` or `@returns` (redundant with TypeScript).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-types.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -63,6 +63,22 @@ 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.
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`, \`TSDeclareFunction\`, \`TSMethodSignature\`,
+\`ClassDeclaration\`). 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/noUndefinedTypes.js

@@ -517,7 +517,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Checks that types in jsdoc comments are defined.',
+      description: 'Besides some expected built-in types, prohibits any types not specified as globals or within `@typedef`.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md#repos-sticky-header',
     },
     schema: [
@@ -525,15 +525,25 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           definedTypes: {
+            description: `This array can be populated to indicate other types which
+are automatically considered as defined (in addition to globals, etc.).
+Defaults to an empty array.`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           disableReporting: {
+            description: `Whether to disable reporting of errors. Defaults to
+\`false\`. This may be set to \`true\` in order to take advantage of only
+marking defined variables as used.`,
             type: 'boolean',
           },
           markVariablesAsUsed: {
+            description: `Whether to mark variables as used for the purposes
+of the \`no-unused-vars\` rule when they are not found to be undefined.
+Defaults to \`true\`. May be set to \`false\` to enforce a practice of not
+importing types unless used in code.`,
             type: 'boolean',
           },
         },

package/src/rules/requireAsteriskPrefix.js

@@ -149,6 +149,12 @@ export default iterateJsdoc(({
     fixable: 'code',
     schema: [
       {
+        description: `If it is \`"always"\` then a problem is raised when there is no asterisk
+prefix on a given JSDoc line. If it is \`"never"\` then a problem is raised
+when there is an asterisk present.
+
+The default value is \`"always"\`. You may also set the default to \`"any"\`
+and use the \`tags\` option to apply to specific tags only.`,
         enum: [
           'always', 'never', 'any',
         ],
@@ -159,20 +165,42 @@ export default iterateJsdoc(({
         properties: {
           tags: {
             additionalProperties: false,
+            description: `If you want different values to apply to specific tags, you may use
+the \`tags\` option object. The keys are \`always\`, \`never\`, or \`any\` and
+the values are arrays of tag names or the special value \`*description\`
+which applies to the main JSDoc block description.
+
+\`\`\`js
+{
+  'jsdoc/require-asterisk-prefix': ['error', 'always', {
+    tags: {
+      always: ['*description'],
+      any: ['example', 'license'],
+      never: ['copyright']
+    }
+  }]
+}
+\`\`\`
+`,
             properties: {
               always: {
+                description: `If it is \`"always"\` then a problem is raised when there is no asterisk
+prefix on a given JSDoc line.`,
                 items: {
                   type: 'string',
                 },
                 type: 'array',
               },
               any: {
+                description: 'No problem is raised regardless of asterisk presence or non-presence.',
                 items: {
                   type: 'string',
                 },
                 type: 'array',
               },
               never: {
+                description: `If it is \`"never"\` then a problem is raised
+when there is an asterisk present.`,
                 items: {
                   type: 'string',
                 },

package/src/rules/requireDescription.js

@@ -99,7 +99,7 @@ export default iterateJsdoc(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that all functions have a description.',
+      description: 'Requires that all functions (and potentially other contexts) have a description.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description.md#repos-sticky-header',
     },
     schema: [
@@ -108,17 +108,38 @@ export default iterateJsdoc(({
         properties: {
           checkConstructors: {
             default: true,
+            description: `A value indicating whether \`constructor\`s should be
+checked. Defaults to \`true\`.`,
             type: 'boolean',
           },
           checkGetters: {
             default: true,
+            description: `A value indicating whether getters should be checked.
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           checkSetters: {
             default: true,
+            description: `A value indicating whether setters should be checked.
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           contexts: {
+            description: `Set to an array of strings representing the AST context
+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 (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: [
                 {
@@ -141,12 +162,20 @@ export default iterateJsdoc(({
             type: 'array',
           },
           descriptionStyle: {
+            description: `Whether to accept implicit descriptions (\`"body"\`) or
+\`@description\` tags (\`"tag"\`) as satisfying the rule. Set to \`"any"\` to
+accept either style. Defaults to \`"body"\`.`,
             enum: [
               'body', 'tag', 'any',
             ],
             type: 'string',
           },
           exemptedBy: {
+            description: `Array of tags (e.g., \`['type']\`) whose presence on the
+document block avoids the need for a \`@description\`. 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.`,
             items: {
               type: 'string',
             },

package/src/rules/requireDescriptionCompleteSentence.js

@@ -312,15 +312,42 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           abbreviations: {
+            description: `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.`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           newlineBeforeCapsAssumesBadSentenceEnd: {
+            description: `When \`false\` (the new default), we will not assume capital letters after
+newlines are an incorrect way to end the sentence (they may be proper
+nouns, for example).`,
             type: 'boolean',
           },
           tags: {
+            description: `If you want additional tags to be checked for their descriptions, you may
+add them within this option.
+
+\`\`\`js
+{
+  'jsdoc/require-description-complete-sentence': ['error', {
+    tags: ['see', 'copyright']
+  }]
+}
+\`\`\`
+
+The tags \`@param\`/\`@arg\`/\`@argument\` and \`@property\`/\`@prop\` will be properly
+parsed to ensure that the checked "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\`).
+`,
             items: {
               type: 'string',
             },

package/src/rules/requireExample.js

@@ -53,7 +53,7 @@ export default iterateJsdoc(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that all functions have examples.',
+      description: 'Requires that all functions (and potentially other contexts) have examples.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -63,17 +63,33 @@ export default iterateJsdoc(({
         properties: {
           checkConstructors: {
             default: true,
+            description: `A value indicating whether \`constructor\`s should be checked.
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           checkGetters: {
             default: false,
+            description: 'A value indicating whether getters should be checked. Defaults to `false`.',
             type: 'boolean',
           },
           checkSetters: {
             default: false,
+            description: 'A value indicating whether setters should be checked. Defaults to `false`.',
             type: 'boolean',
           },
           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: [
                 {
@@ -97,9 +113,16 @@ export default iterateJsdoc(({
           },
           enableFixer: {
             default: true,
+            description: `A boolean on whether to enable the fixer (which adds an empty \`@example\` block).
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           exemptedBy: {
+            description: `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.`,
             items: {
               type: 'string',
             },
@@ -107,6 +130,8 @@ export default iterateJsdoc(({
           },
           exemptNoArguments: {
             default: false,
+            description: `Boolean to indicate that no-argument functions should not be reported for
+missing \`@example\` declarations.`,
             type: 'boolean',
           },
         },

package/src/rules/requireFileOverview.js

@@ -118,6 +118,67 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           tags: {
+            description: `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 3 potential boolean keys (which default
+to \`false\` when this option is supplied).
+
+1. \`mustExist\` - enforces that all files have a \`@file\`, \`@fileoverview\`, or \`@overview\` tag.
+2. \`preventDuplicates\` - enforces that duplicate file overview tags within a given file will be reported
+3. \`initialCommentsOnly\` - reports file overview tags 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.
+
+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).
+
+`,
             patternProperties: {
               '.*': {
                 additionalProperties: false,

package/src/rules/requireHyphenBeforeParamDescription.js

@@ -149,12 +149,20 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Requires a hyphen before the `@param` description.',
+      description: 'Requires a hyphen before the `@param` description (and optionally before `@property` descriptions).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',
     },
     fixable: 'code',
     schema: [
       {
+        description: `If the string is \`"always"\` then a problem is raised when there is no hyphen
+before the description. If it is \`"never"\` then a problem is raised when there
+is a hyphen before the description. The default value is \`"always"\`.
+
+Even if hyphens are set to "always" appear after the tag name, they will
+actually be forbidden in the event that they are followed immediately by
+the end of a line (this will otherwise cause Visual Studio Code to display
+incorrectly).`,
         enum: [
           'always', 'never',
         ],
@@ -162,6 +170,8 @@ export default iterateJsdoc(({
       },
       {
         additionalProperties: false,
+        description: `The options object may have the following property to indicate behavior for
+other tags besides the \`@param\` tag (or the \`@arg\` tag if so set).`,
         properties: {
           tags: {
             anyOf: [
@@ -183,6 +193,14 @@ export default iterateJsdoc(({
                 type: 'string',
               },
             ],
+            description: `Object whose keys indicate different tags to check for the
+  presence or absence of hyphens; the key value should be "always" or "never",
+  indicating how hyphens are to be applied, e.g., \`{property: 'never'}\`
+  to ensure \`@property\` never uses hyphens. A key can also be set as \`*\`, e.g.,
+  \`'*': 'always'\` to apply hyphen checking to any tag (besides the preferred
+  \`@param\` tag which follows the main string option setting and besides any
+  other \`tags\` entries).
+`,
           },
         },
         type: 'object',