eslint-plugin-jsdoc 58.1.0 → 59.0.0

package/src/rules/requireJsdoc.js

@@ -34,9 +34,13 @@ import {
 /** @type {import('json-schema').JSONSchema4} */
 const OPTIONS_SCHEMA = {
   additionalProperties: false,
+  description: 'Has the following optional keys.\n',
   properties: {
     checkConstructors: {
       default: true,
+      description: `A value indicating whether \`constructor\`s should be checked. Defaults to
+\`true\`. When \`true\`, \`exemptEmptyConstructors\` may still avoid reporting when
+no parameters or return values are found.`,
       type: 'boolean',
     },
     checkGetters: {
@@ -52,6 +56,12 @@ const OPTIONS_SCHEMA = {
         },
       ],
       default: true,
+      description: `A value indicating whether getters should be checked. Besides setting as a
+boolean, this option can be set to the string \`"no-setter"\` to indicate that
+getters should be checked but only when there is no setter. This may be useful
+if one only wishes documentation on one of the two accessors. Defaults to
+\`false\`.
+`,
     },
     checkSetters: {
       anyOf: [
@@ -66,8 +76,28 @@ const OPTIONS_SCHEMA = {
         },
       ],
       default: true,
+      description: `A value indicating whether setters should be checked. Besides setting as a
+boolean, this option can be set to the string \`"no-getter"\` to indicate that
+setters should be checked but only when there is no getter. This may be useful
+if one only wishes documentation on one of the two accessors. Defaults to
+\`false\`.`,
     },
     contexts: {
+      description: `Set this to an array of strings or objects representing the additional AST
+contexts where you wish the rule to be applied (e.g., \`Property\` for
+properties). If specified as an object, it should have a \`context\` property
+and can have an \`inlineCommentBlock\` property which, if set to \`true\`, will
+add an inline \`/** */\` instead of the regular, multi-line, indented jsdoc
+block which will otherwise be added. Defaults to an empty array. Contexts
+may also have their own \`minLineCount\` property which is an integer
+indicating a minimum number of lines expected for a node in order
+for it to require documentation.
+
+Note that you may need to disable \`require\` items (e.g., \`MethodDefinition\`)
+if you are specifying a more precise form in \`contexts\` (e.g., \`MethodDefinition:not([accessibility="private"] > FunctionExpression\`).
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
       items: {
         anyOf: [
           {
@@ -94,28 +124,62 @@ const OPTIONS_SCHEMA = {
     },
     enableFixer: {
       default: true,
+      description: `A boolean on whether to enable the fixer (which adds an empty JSDoc block).
+Defaults to \`true\`.`,
       type: 'boolean',
     },
     exemptEmptyConstructors: {
       default: false,
+      description: `When \`true\`, the rule will not report missing JSDoc blocks above constructors
+with no parameters or return values (this is enabled by default as the class
+name or description should be seen as sufficient to convey intent).
+
+Defaults to \`true\`.`,
       type: 'boolean',
     },
     exemptEmptyFunctions: {
       default: false,
+      description: `When \`true\`, the rule will not report missing JSDoc blocks above
+functions/methods with no parameters or return values (intended where
+function/method names are sufficient for themselves as documentation).
+
+Defaults to \`false\`.
+`,
       type: 'boolean',
     },
     exemptOverloadedImplementations: {
       default: false,
+      description: `If set to \`true\` will avoid checking an overloaded function's implementation.
+
+Defaults to \`false\`.`,
       type: 'boolean',
     },
     fixerMessage: {
       default: '',
+      description: `An optional message to add to the inserted JSDoc block. Defaults to the
+empty string.`,
       type: 'string',
     },
     minLineCount: {
+      description: `An integer to indicate a minimum number of lines expected for a node in order
+for it to require documentation. Defaults to \`undefined\`. This option will
+apply to any context; see \`contexts\` for line counts specific to a context.`,
       type: 'integer',
     },
     publicOnly: {
+      description: `This option will insist that missing JSDoc blocks are only reported for
+function bodies / class declarations that are exported from the module.
+May be a boolean or object. If set to \`true\`, the defaults below will be
+used. If unset, JSDoc block reporting will not be limited to exports.
+
+This object supports the following optional boolean keys (\`false\` unless
+otherwise noted):
+
+- \`ancestorsOnly\` - Optimization to only check node ancestors to check if node is exported
+- \`esm\` - ESM exports are checked for JSDoc comments (Defaults to \`true\`)
+- \`cjs\` - CommonJS exports are checked for JSDoc comments  (Defaults to \`true\`)
+- \`window\` - Window global exports are checked for JSDoc comments
+`,
       oneOf: [
         {
           default: false,
@@ -145,29 +209,37 @@ const OPTIONS_SCHEMA = {
     require: {
       additionalProperties: false,
       default: {},
+      description: `An object with the following optional boolean keys which all default to
+\`false\` except for \`FunctionDeclaration\` which defaults to \`true\`.`,
       properties: {
         ArrowFunctionExpression: {
           default: false,
+          description: 'Whether to check arrow functions like `() => {}`',
           type: 'boolean',
         },
         ClassDeclaration: {
           default: false,
+          description: 'Whether to check declarations like `class A {}`',
           type: 'boolean',
         },
         ClassExpression: {
           default: false,
+          description: 'Whether to check class expressions like `const myClass = class {}`',
           type: 'boolean',
         },
         FunctionDeclaration: {
           default: true,
+          description: 'Whether to check function declarations like `function a {}`',
           type: 'boolean',
         },
         FunctionExpression: {
           default: false,
+          description: 'Whether to check function expressions like `const a = function {}`',
           type: 'boolean',
         },
         MethodDefinition: {
           default: false,
+          description: 'Whether to check method definitions like `class A { someMethodDefinition () {} }`',
           type: 'boolean',
         },
       },
@@ -175,6 +247,13 @@ const OPTIONS_SCHEMA = {
     },
     skipInterveningOverloadedDeclarations: {
       default: true,
+      description: `If \`true\`, will skip above uncommented overloaded functions to check
+for a comment block (e.g., at the top of a set of overloaded functions).
+
+If \`false\`, will force each overloaded function to be checked for a
+comment block.
+
+Defaults to \`true\`.`,
       type: 'boolean',
     },
   },
@@ -790,7 +869,7 @@ export default {
   meta: {
     docs: {
       category: 'Stylistic Issues',
-      description: 'Require JSDoc comments',
+      description: 'Checks for presence of JSDoc comments, on functions and potentially other contexts (optionally limited to exports).',
       recommended: true,
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-jsdoc.md#repos-sticky-header',
     },

package/src/rules/requireParam.js

@@ -517,7 +517,7 @@ export default iterateJsdoc(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that all function parameters are documented.',
+      description: 'Requires that all function parameters are documented with a `@param` tag.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -527,36 +527,150 @@ export default iterateJsdoc(({
         properties: {
           autoIncrementBase: {
             default: 0,
+            description: `Numeric to indicate the number at which to begin auto-incrementing roots.
+Defaults to \`0\`.
+`,
             type: 'integer',
           },
           checkConstructors: {
             default: true,
+            description: `A value indicating whether \`constructor\`s should be checked. Defaults to
+\`true\`.
+`,
             type: 'boolean',
           },
           checkDestructured: {
             default: true,
+            description: 'Whether to require destructured properties. Defaults to `true`.',
             type: 'boolean',
           },
           checkDestructuredRoots: {
             default: true,
+            description: `Whether to check the existence of a corresponding \`@param\` for root objects
+of destructured properties (e.g., that for \`function ({a, b}) {}\`, that there
+is something like \`@param myRootObj\` defined that can correspond to
+the \`{a, b}\` object parameter).
+
+If \`checkDestructuredRoots\` is \`false\`, \`checkDestructured\` will also be
+implied to be \`false\` (i.e., the inside of the roots will not be checked
+either, e.g., it will also not complain if \`a\` or \`b\` do not have their own
+documentation). Defaults to \`true\`.
+`,
             type: 'boolean',
           },
           checkGetters: {
             default: false,
+            description: 'A value indicating whether getters should be checked. Defaults to `false`.',
             type: 'boolean',
           },
           checkRestProperty: {
             default: false,
+            description: `If set to \`true\`, will report (and add fixer insertions) for missing rest
+properties. Defaults to \`false\`.
+
+If set to \`true\`, note that you can still document the subproperties of the
+rest property using other jsdoc features, e.g., \`@typedef\`:
+
+\`\`\`js
+/**
+ * @typedef ExtraOptions
+ * @property innerProp1
+ * @property innerProp2
+ */
+
+/**
+ * @param cfg
+ * @param cfg.num
+ * @param {ExtraOptions} extra
+ */
+function quux ({num, ...extra}) {
+}
+\`\`\`
+
+Setting this option to \`false\` (the default) may be useful in cases where
+you already have separate \`@param\` definitions for each of the properties
+within the rest property.
+
+For example, with the option disabled, this will not give an error despite
+\`extra\` not having any definition:
+
+\`\`\`js
+/**
+ * @param cfg
+ * @param cfg.num
+ */
+function quux ({num, ...extra}) {
+}
+\`\`\`
+
+Nor will this:
+
+\`\`\`js
+/**
+ * @param cfg
+ * @param cfg.num
+ * @param cfg.innerProp1
+ * @param cfg.innerProp2
+ */
+function quux ({num, ...extra}) {
+}
+\`\`\`
+`,
             type: 'boolean',
           },
           checkSetters: {
             default: false,
+            description: 'A value indicating whether setters should be checked. Defaults to `false`.',
             type: 'boolean',
           },
           checkTypesPattern: {
+            description: `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',
           },
           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\`). May be useful for adding such as
+\`TSMethodSignature\` in TypeScript or restricting the contexts
+which are checked.
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.
+`,
             items: {
               anyOf: [
                 {
@@ -579,33 +693,131 @@ export default iterateJsdoc(({
             type: 'array',
           },
           enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `true`.',
             type: 'boolean',
           },
           enableRestElementFixer: {
+            description: `Whether to enable the rest element fixer.
+
+The fixer will automatically report/insert
+[JSDoc repeatable parameters](https://jsdoc.app/tags-param.html#multiple-types-and-repeatable-parameters)
+if missing.
+
+\`\`\`js
+/**
+  * @param {GenericArray} cfg
+  * @param {number} cfg."0"
+ */
+function baar ([a, ...extra]) {
+  //
+}
+\`\`\`
+
+...becomes:
+
+\`\`\`js
+/**
+  * @param {GenericArray} cfg
+  * @param {number} cfg."0"
+  * @param {...any} cfg."1"
+ */
+function baar ([a, ...extra]) {
+  //
+}
+\`\`\`
+
+Note that the type \`any\` is included since we don't know of any specific
+type to use.
+
+Defaults to \`true\`.
+`,
             type: 'boolean',
           },
           enableRootFixer: {
+            description: `Whether to enable the auto-adding of incrementing roots.
+
+The default behavior of \`true\` is for "root" to be auto-inserted for missing
+roots, followed by a 0-based auto-incrementing number.
+
+So for:
+
+\`\`\`js
+function quux ({foo}, {bar}, {baz}) {
+}
+\`\`\`
+
+...the default JSDoc that would be added if the fixer is enabled would be:
+
+\`\`\`js
+/**
+* @param root0
+* @param root0.foo
+* @param root1
+* @param root1.bar
+* @param root2
+* @param root2.baz
+*/
+\`\`\`
+
+Has no effect if \`enableFixer\` is set to \`false\`.`,
             type: 'boolean',
           },
           exemptedBy: {
+            description: `Array of tags (e.g., \`['type']\`) whose presence on the document block
+avoids the need for a \`@param\`. 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',
             },
             type: 'array',
           },
           ignoreWhenAllParamsMissing: {
+            description: `Set to \`true\` to ignore reporting when all params are missing. Defaults to
+\`false\`.`,
             type: 'boolean',
           },
           interfaceExemptsParamsCheck: {
+            description: `Set if you wish TypeScript interfaces to exempt checks for the existence of
+\`@param\`'s.
+
+Will check for a type defining the function itself (on a variable
+declaration) or if there is a single destructured object with a type.
+Defaults to \`false\`.`,
             type: 'boolean',
           },
           unnamedRootBase: {
+            description: `An array of root names to use in the fixer when roots are missing. Defaults
+to \`['root']\`. Note that only when all items in the array besides the last
+are exhausted will auto-incrementing occur. So, with
+\`unnamedRootBase: ['arg', 'config']\`, the following:
+
+\`\`\`js
+function quux ({foo}, [bar], {baz}) {
+}
+\`\`\`
+
+...will get the following JSDoc block added:
+
+\`\`\`js
+/**
+* @param arg
+* @param arg.foo
+* @param config0
+* @param config0."0" (\`bar\`)
+* @param config1
+* @param config1.baz
+*/
+\`\`\``,
             items: {
               type: 'string',
             },
             type: 'array',
           },
           useDefaultObjectProperties: {
+            description: `Set to \`true\` if you wish to expect documentation of properties on objects
+supplied as default values. Defaults to \`false\`.`,
             type: 'boolean',
           },
         },

package/src/rules/requireParamDescription.js

@@ -53,6 +53,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: [
                 {
@@ -75,9 +89,16 @@ export default iterateJsdoc(({
             type: 'array',
           },
           defaultDestructuredRootDescription: {
+            description: `The description string to set by default for destructured roots. Defaults to
+"The root object".`,
             type: 'string',
           },
           setDefaultDestructuredRootDescription: {
+            description: `Whether to set a default destructured root description. For example, you may
+wish to avoid manually having to set the description for a \`@param\`
+corresponding to a destructured root object as it should always be the same
+type of object. Uses \`defaultDestructuredRootDescription\` for the description
+string. Defaults to \`false\`.`,
             type: 'boolean',
           },
         },

package/src/rules/requireParamName.js

@@ -17,7 +17,7 @@ export default iterateJsdoc(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that all function parameters have names.',
+      description: 'Requires that all `@param` tags have names.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-name.md#repos-sticky-header',
     },
     schema: [
@@ -25,6 +25,21 @@ 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: [
                 {

package/src/rules/requireParamType.js

@@ -44,7 +44,7 @@ export default iterateJsdoc(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that each `@param` tag has a `type` value.',
+      description: 'Requires that each `@param` tag has a type value (in curly brackets).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-type.md#repos-sticky-header',
     },
     fixable: 'code',
@@ -53,6 +53,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: [
                 {
@@ -75,9 +89,15 @@ export default iterateJsdoc(({
             type: 'array',
           },
           defaultDestructuredRootType: {
+            description: 'The type string to set by default for destructured roots. Defaults to "object".',
             type: 'string',
           },
           setDefaultDestructuredRootType: {
+            description: `Whether to set a default destructured root type. For example, you may wish
+to avoid manually having to set the type for a \`@param\`
+corresponding to a destructured root object as it is always going to be an
+object. Uses \`defaultDestructuredRootType\` for the type string. Defaults to
+\`false\`.`,
             type: 'boolean',
           },
         },

package/src/rules/requirePropertyName.js

@@ -17,7 +17,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Requires that all function `@property` tags have names.',
+      description: 'Requires that all `@property` tags have names.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-name.md#repos-sticky-header',
     },
     type: 'suggestion',

package/src/rules/requirePropertyType.js

@@ -17,7 +17,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Requires that each `@property` tag has a `type` value.',
+      description: 'Requires that each `@property` tag has a type value (in curly brackets).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-type.md#repos-sticky-header',
     },
     type: 'suggestion',