eslint-plugin-jsdoc 58.1.0 → 59.0.0

package/package.json

@@ -172,5 +172,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "58.1.0"
+  "version": "59.0.0"
 }

package/src/buildForbidRuleDefinition.js

@@ -59,7 +59,6 @@ export const buildForbidRuleDefinition = ({
         description: description ?? contextName ?? 'Reports when certain comment structures are present.',
         url: url ?? 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/advanced.md#user-content-advanced-creating-your-own-rules',
       },
-      fixable: 'code',
       schema: [],
       type: 'suggestion',
     },

package/src/buildRejectOrPreferRuleDefinition.js

@@ -111,7 +111,7 @@ const infoUC = {
 export const buildRejectOrPreferRuleDefinition = ({
   checkNativeTypes = null,
   typeName,
-  description = typeName ?? 'Reports invalid types.',
+  description = typeName ?? 'Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements).',
   overrideSettings = null,
   schema = [],
   url = 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-types.md#repos-sticky-header',
@@ -463,7 +463,17 @@ export const buildRejectOrPreferRuleDefinition = ({
           description,
           url,
         },
-        fixable: 'code',
+        ...(!overrideSettings || (Object.values(overrideSettings).some((os) => {
+          return os && typeof os === 'object' ?
+            /* c8 ignore next -- Ok */
+            os.replacement :
+            typeof os === 'string';
+        })) ?
+          {
+            fixable: 'code',
+          } :
+          {}
+        ),
         schema,
         type: 'suggestion',
       },

package/src/index-cjs.js

@@ -144,6 +144,17 @@ index.rules = {
   'require-file-overview': requireFileOverview,
   'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
   'require-jsdoc': requireJsdoc,
+  'require-next-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=next]:not([name!=""]))',
+        context: 'any',
+        message: '@next should have a description',
+      },
+    ],
+    description: 'Requires a description for `@next` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-next-description.md#repos-sticky-header',
+  }),
   'require-next-type': buildForbidRuleDefinition({
     contexts: [
       {
@@ -169,6 +180,17 @@ index.rules = {
   'require-returns-type': requireReturnsType,
   'require-template': requireTemplate,
   'require-throws': requireThrows,
+  'require-throws-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=throws]:not([description!=""]))',
+        context: 'any',
+        message: '@throws should have a description',
+      },
+    ],
+    description: 'Requires a description for `@throws` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws-description.md#repos-sticky-header',
+  }),
   'require-throws-type': buildForbidRuleDefinition({
     contexts: [
       {
@@ -182,6 +204,17 @@ index.rules = {
   }),
   'require-yields': requireYields,
   'require-yields-check': requireYieldsCheck,
+  'require-yields-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=yields]:not([name!=""]))',
+        context: 'any',
+        message: '@yields should have a description',
+      },
+    ],
+    description: 'Requires a description for `@yields` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-description.md#repos-sticky-header',
+  }),
   'require-yields-type': buildForbidRuleDefinition({
     contexts: [
       {
@@ -257,6 +290,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-file-overview': 'off',
       'jsdoc/require-hyphen-before-param-description': 'off',
       'jsdoc/require-jsdoc': warnOrError,
+      'jsdoc/require-next-description': 'off',
       'jsdoc/require-next-type': warnOrError,
       'jsdoc/require-param': warnOrError,
       'jsdoc/require-param-description': warnOrError,
@@ -272,9 +306,11 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-type': warnOrError,
       'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
+      'jsdoc/require-throws-description': 'off',
       'jsdoc/require-throws-type': warnOrError,
       'jsdoc/require-yields': warnOrError,
       'jsdoc/require-yields-check': warnOrError,
+      'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,

package/src/index.js

@@ -150,6 +150,17 @@ index.rules = {
   'require-file-overview': requireFileOverview,
   'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
   'require-jsdoc': requireJsdoc,
+  'require-next-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=next]:not([name!=""]))',
+        context: 'any',
+        message: '@next should have a description',
+      },
+    ],
+    description: 'Requires a description for `@next` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-next-description.md#repos-sticky-header',
+  }),
   'require-next-type': buildForbidRuleDefinition({
     contexts: [
       {
@@ -175,6 +186,17 @@ index.rules = {
   'require-returns-type': requireReturnsType,
   'require-template': requireTemplate,
   'require-throws': requireThrows,
+  'require-throws-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=throws]:not([description!=""]))',
+        context: 'any',
+        message: '@throws should have a description',
+      },
+    ],
+    description: 'Requires a description for `@throws` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws-description.md#repos-sticky-header',
+  }),
   'require-throws-type': buildForbidRuleDefinition({
     contexts: [
       {
@@ -188,6 +210,17 @@ index.rules = {
   }),
   'require-yields': requireYields,
   'require-yields-check': requireYieldsCheck,
+  'require-yields-description': buildForbidRuleDefinition({
+    contexts: [
+      {
+        comment: 'JsdocBlock:has(JsdocTag[tag=yields]:not([name!=""]))',
+        context: 'any',
+        message: '@yields should have a description',
+      },
+    ],
+    description: 'Requires a description for `@yields` tags',
+    url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-description.md#repos-sticky-header',
+  }),
   'require-yields-type': buildForbidRuleDefinition({
     contexts: [
       {
@@ -263,6 +296,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-file-overview': 'off',
       'jsdoc/require-hyphen-before-param-description': 'off',
       'jsdoc/require-jsdoc': warnOrError,
+      'jsdoc/require-next-description': 'off',
       'jsdoc/require-next-type': warnOrError,
       'jsdoc/require-param': warnOrError,
       'jsdoc/require-param-description': warnOrError,
@@ -278,9 +312,11 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/require-returns-type': warnOrError,
       'jsdoc/require-template': 'off',
       'jsdoc/require-throws': 'off',
+      'jsdoc/require-throws-description': 'off',
       'jsdoc/require-throws-type': warnOrError,
       'jsdoc/require-yields': warnOrError,
       'jsdoc/require-yields-check': warnOrError,
+      'jsdoc/require-yields-description': 'off',
       'jsdoc/require-yields-type': warnOrError,
       'jsdoc/sort-tags': 'off',
       'jsdoc/tag-lines': warnOrError,

package/src/rules/checkAccess.js

@@ -29,7 +29,7 @@ export default iterateJsdoc(({
 
   if (accessLength > 1 || individualTagLength > 1) {
     report(
-      'At most one access-control tag may be present on a jsdoc block.',
+      'At most one access-control tag may be present on a JSDoc block.',
     );
   }
 }, {

package/src/rules/checkAlignment.js

@@ -69,9 +69,12 @@ export default iterateJsdoc(({
         properties: {
           innerIndent: {
             default: 1,
+            description: `Set to 0 if you wish to avoid the normal requirement for an inner indentation of
+one space. Defaults to 1 (one space of normal inner indentation).`,
             type: 'integer',
           },
         },
+        type: 'object',
       },
     ],
     type: 'layout',

package/src/rules/checkExamples.js

@@ -536,7 +536,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.',
+      description: 'Ensures that (JavaScript) samples within `@example` tags adhere to ESLint rules.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-examples.md#repos-sticky-header',
     },
     schema: [

package/src/rules/checkIndentation.js

@@ -60,6 +60,25 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           excludeTags: {
+            description: `Array of tags (e.g., \`['example', 'description']\`) whose content will be
+"hidden" from the \`check-indentation\` rule. Defaults to \`['example']\`.
+
+By default, the whole JSDoc block will be checked for invalid padding.
+That would include \`@example\` blocks too, which can get in the way
+of adding full, readable examples of code without ending up with multiple
+linting issues.
+
+When disabled (by passing \`excludeTags: []\` option), the following code *will*
+report a padding issue:
+
+\`\`\`js
+/**
+ * @example
+ * anArray.filter((a) => {
+ *   return a.b;
+ * });
+ */
+\`\`\``,
             items: {
               pattern: '^\\S+$',
               type: 'string',

package/src/rules/checkLineAlignment.js

@@ -319,6 +319,14 @@ export default iterateJsdoc(({
     fixable: 'whitespace',
     schema: [
       {
+        description: `If the string value is
+\`"always"\` then a problem is raised when the lines are not aligned.
+If it is \`"never"\` then a problem should be raised when there is more than
+one space between each line's parts. If it is \`"any"\`, no alignment is made.
+Defaults to \`"never"\`.
+
+Note that in addition to alignment, the "never" and "always" options will both
+ensure that at least one space is present after the asterisk delimiter.`,
         enum: [
           'always', 'never', 'any',
         ],
@@ -329,38 +337,54 @@ export default iterateJsdoc(({
         properties: {
           customSpacings: {
             additionalProperties: false,
+            description: `An object with any of the following spacing keys set to an integer.
+If a spacing is not defined, it defaults to one.
+`,
             properties: {
               postDelimiter: {
+                description: 'Affects spacing after the asterisk (e.g., `*   @param`)',
                 type: 'integer',
               },
               postHyphen: {
+                description: 'Affects spacing after any hyphens in the description (e.g., `* @param {someType} name -  A description`)',
                 type: 'integer',
               },
               postName: {
+                description: 'Affects spacing after the name (e.g., `* @param {someType} name   `)',
                 type: 'integer',
               },
               postTag: {
+                description: 'Affects spacing after the tag (e.g., `* @param  `)',
                 type: 'integer',
               },
               postType: {
+                description: 'Affects spacing after the type (e.g., `* @param {someType}   `)',
                 type: 'integer',
               },
             },
+            type: 'object',
           },
           disableWrapIndent: {
+            description: 'Disables `wrapIndent`; existing wrap indentation is preserved without changes.',
             type: 'boolean',
           },
           preserveMainDescriptionPostDelimiter: {
             default: false,
+            description: `A boolean to determine whether to preserve the post-delimiter spacing of the
+main description. If \`false\` or unset, will be set to a single space.`,
             type: 'boolean',
           },
           tags: {
+            description: `Use this to change the tags which are sought for alignment changes. Defaults to an array of
+\`['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template']\`.`,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           wrapIndent: {
+            description: `The indent that will be applied for tag text after the first line.
+Default to the empty string (no indent).`,
             type: 'string',
           },
         },

package/src/rules/checkParamNames.js

@@ -433,7 +433,7 @@ export default iterateJsdoc(({
   contextDefaults: allowedNodes,
   meta: {
     docs: {
-      description: 'Ensures that parameter names in JSDoc match those in the function declaration.',
+      description: 'Checks for dupe `@param` names, that nested param names have roots, and that parameter names in function declarations match JSDoc param names.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-param-names.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -442,27 +442,88 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           allowExtraTrailingParamDocs: {
+            description: `If set to \`true\`, this option will allow extra \`@param\` definitions (e.g.,
+representing future expected or virtual params) to be present without needing
+their presence within the function signature. Other inconsistencies between
+\`@param\`'s and present function parameters will still be reported.`,
             type: 'boolean',
           },
           checkDestructured: {
+            description: 'Whether to check destructured properties. Defaults to `true`.',
             type: 'boolean',
           },
           checkRestProperty: {
+            description: `If set to \`true\`, will require that rest properties are documented and
+that any extraneous properties (which may have been within the rest property)
+are documented. Defaults to \`false\`.`,
             type: 'boolean',
           },
           checkTypesPattern: {
+            description: `Defines a regular expression pattern to indicate which types should be
+checked for destructured content (and that those not matched should not
+be checked).
+
+When one specifies a type, unless it is of a generic type, like \`object\`
+or \`array\`, it may be considered unnecessary to have that object's
+destructured components required, especially where generated docs will
+link back to the specified type. For example:
+
+\`\`\`js
+/**
+ * @param {SVGRect} bbox - a SVGRect
+ */
+export const bboxToObj = function ({x, y, width, height}) {
+  return {x, y, width, height};
+};
+\`\`\`
+
+By default \`checkTypesPattern\` is set to
+\`/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/v\`,
+meaning that destructuring will be required only if the type of the \`@param\`
+(the text between curly brackets) is a match for "Object" or "Array" (with or
+without initial caps), "PlainObject", or "GenericObject", "GenericArray" (or
+if no type is present). So in the above example, the lack of a match will
+mean that no complaint will be given about the undocumented destructured
+parameters.
+
+Note that the \`/\` delimiters are optional, but necessary to add flags.
+
+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., \`/^object$/vi\`.
+
+You could set this regular expression to a more expansive list, or you
+could restrict it such that even types matching those strings would not
+need destructuring.`,
             type: 'string',
           },
           disableExtraPropertyReporting: {
+            description: `Whether to check for extra destructured properties. Defaults to \`false\`. Change
+to \`true\` if you want to be able to document properties which are not actually
+destructured. Keep as \`false\` if you expect properties to be documented in
+their own types. Note that extra properties will always be reported if another
+item at the same level is destructured as destructuring will prevent other
+access and this option is only intended to permit documenting extra properties
+that are available and actually used in the function.`,
             type: 'boolean',
           },
           disableMissingParamChecks: {
+            description: 'Whether to avoid checks for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.',
             type: 'boolean',
           },
           enableFixer: {
+            description: `Set to \`true\` to auto-remove \`@param\` duplicates (based on identical
+names).
+
+Note that this option will remove duplicates of the same name even if
+the definitions do not match in other ways (e.g., the second param will
+be removed even if it has a different type or description).`,
             type: 'boolean',
           },
           useDefaultObjectProperties: {
+            description: `Set to \`true\` if you wish to avoid reporting of child property documentation
+where instead of destructuring, a whole plain object is supplied as default
+value but you wish its keys to be considered as signalling that the properties
+are present and can therefore be documented. Defaults to \`false\`.`,
             type: 'boolean',
           },
         },

package/src/rules/checkPropertyNames.js

@@ -141,6 +141,12 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           enableFixer: {
+            description: `Set to \`true\` to auto-remove \`@property\` duplicates (based on
+identical names).
+
+Note that this option will remove duplicates of the same name even if
+the definitions do not match in other ways (e.g., the second property will
+be removed even if it has a different type or description).`,
             type: 'boolean',
           },
         },

package/src/rules/checkTagNames.js

@@ -291,18 +291,89 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           definedTags: {
+            description: `Use an array of \`definedTags\` strings to configure additional, allowed tags.
+The format is as follows:
+
+\`\`\`json
+{
+  "definedTags": ["note", "record"]
+}
+\`\`\``,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           enableFixer: {
+            description: 'Set to `false` to disable auto-removal of types that are redundant with the [`typed` option](#typed).',
             type: 'boolean',
           },
           jsxTags: {
+            description: `If this is set to \`true\`, all of the following tags used to control JSX output are allowed:
+
+\`\`\`
+jsx
+jsxFrag
+jsxImportSource
+jsxRuntime
+\`\`\`
+
+For more information, see the [babel documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx).`,
             type: 'boolean',
           },
           typed: {
+            description: `If this is set to \`true\`, additionally checks for tag names that are redundant when using a type checker such as TypeScript.
+
+These tags are always unnecessary when using TypeScript or similar:
+
+\`\`\`
+augments
+callback
+class
+enum
+implements
+private
+property
+protected
+public
+readonly
+this
+type
+typedef
+\`\`\`
+
+These tags are unnecessary except when inside a TypeScript \`declare\` context:
+
+\`\`\`
+abstract
+access
+class
+constant
+constructs
+default
+enum
+export
+exports
+function
+global
+inherits
+instance
+interface
+member
+memberof
+memberOf
+method
+mixes
+mixin
+module
+name
+namespace
+override
+property
+requires
+static
+this
+\`\`\``,
             type: 'boolean',
           },
         },

package/src/rules/checkTypes.js

@@ -89,13 +89,24 @@ export default buildRejectOrPreferRuleDefinition({
       additionalProperties: false,
       properties: {
         exemptTagContexts: {
+          description: 'Avoids reporting when a bad type is found on a specified tag.',
           items: {
             additionalProperties: false,
             properties: {
               tag: {
+                description: 'Set a key `tag` to the tag to exempt',
                 type: 'string',
               },
               types: {
+                description: `Set to \`true\` to indicate that any types on that tag will be allowed,
+or to an array of strings which will only allow specific bad types.
+If an array of strings is given, these must match the type exactly,
+e.g., if you only allow \`"object"\`, it will not allow
+\`"object<string, string>"\`. Note that this is different from the
+behavior of \`settings.jsdoc.preferredTypes\`. This option is useful
+for normally restricting generic types like \`object\` with
+\`preferredTypes\`, but allowing \`typedef\` to indicate that its base
+type is \`object\`.`,
                 oneOf: [
                   {
                     type: 'boolean',
@@ -114,10 +125,14 @@ export default buildRejectOrPreferRuleDefinition({
           type: 'array',
         },
         noDefaults: {
+          description: `Insists that only the supplied option type
+map is to be used, and that the default preferences (such as "string"
+over "String") will not be enforced. The option's default is \`false\`.`,
           type: 'boolean',
         },
         unifyParentAndChildTypeChecks: {
-          description: '@deprecated Use the `preferredTypes[preferredType]` setting of the same name instead',
+          description: `@deprecated Use the \`preferredTypes[preferredType]\` setting of the same name instead.
+If this option is \`true\`, will currently override \`unifyParentAndChildTypeChecks\` on the \`preferredTypes\` setting.`,
           type: 'boolean',
         },
       },

package/src/rules/checkValues.js

@@ -215,6 +215,8 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           allowedAuthors: {
+            description: `An array of allowable author values. If absent, only non-whitespace will
+be checked for.`,
             items: {
               type: 'string',
             },
@@ -232,11 +234,25 @@ export default iterateJsdoc(({
                 type: 'boolean',
               },
             ],
+            description: `An array of allowable license values or \`true\` to allow any license text.
+If present as an array, will be used in place of [SPDX identifiers](https://spdx.org/licenses/).`,
           },
           licensePattern: {
+            description: `A string to be converted into a \`RegExp\` (with \`v\` 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\\r]*)/gv\`, i.e., the SPDX expression
+is expected before any line breaks.
+
+Note that the \`/\` delimiters are optional, but necessary to add flags.
+
+Defaults to using the \`v\` flag, so to add your own flags, encapsulate
+your expression as a string, but like a literal, e.g., \`/^mit$/vi\`.`,
             type: 'string',
           },
           numericOnlyVariation: {
+            description: `Whether to enable validation that \`@variation\` must be a number. Defaults to
+\`false\`.`,
             type: 'boolean',
           },
         },