eslint-plugin-jsdoc 58.1.0 → 59.0.0

package/src/rules/tagLines.js

@@ -296,6 +296,11 @@ export default iterateJsdoc(({
     fixable: 'code',
     schema: [
       {
+        description: `Defaults to "never". "any" is only useful with \`tags\` (allowing non-enforcement of lines except
+for particular tags) or with \`startLines\` or \`endLines\`. It is also
+necessary if using the linebreak-setting options of the \`sort-tags\` rule
+so that the two rules won't conflict in both attempting to set lines
+between tags.`,
         enum: [
           'always', 'any', 'never',
         ],
@@ -305,9 +310,16 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           applyToEndTag: {
+            description: `Set to \`false\` and use with "always" to indicate the normal lines to be
+added after tags should not be added after the final tag.
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           count: {
+            description: `Use with "always" to indicate the number of lines to require be present.
+
+Defaults to 1.`,
             type: 'integer',
           },
           endLines: {
@@ -319,6 +331,10 @@ export default iterateJsdoc(({
                 type: 'null',
               },
             ],
+            description: `If not set to \`null\`, will enforce end lines to the given count on the
+final tag only.
+
+Defaults to \`0\`.`,
           },
           startLines: {
             anyOf: [
@@ -329,8 +345,22 @@ export default iterateJsdoc(({
                 type: 'null',
               },
             ],
+            description: `If not set to \`null\`, will enforce end lines to the given count before the
+first tag only, unless there is only whitespace content, in which case,
+a line count will not be enforced.
+
+Defaults to \`0\`.`,
           },
           tags: {
+            description: `Overrides the default behavior depending on specific tags.
+
+An object whose keys are tag names and whose values are objects with the
+following keys:
+
+1. \`lines\` - Set to \`always\`, \`never\`, or \`any\` to override.
+2. \`count\` - Overrides main \`count\` (for "always")
+
+Defaults to empty object.`,
             patternProperties: {
               '.*': {
                 additionalProperties: false,

package/src/rules/textEscaping.js

@@ -138,11 +138,15 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
-          // Option properties here (or remove the object)
           escapeHTML: {
+            description: `This option escapes all \`<\` and \`&\` characters (except those followed by
+whitespace which are treated as literals by Visual Studio Code). Defaults to
+\`false\`.`,
             type: 'boolean',
           },
           escapeMarkdown: {
+            description: `This option escapes the first backtick (\`\` \` \`\`) in a paired sequence.
+Defaults to \`false\`.`,
             type: 'boolean',
           },
         },

package/src/rules/typeFormatting.js

@@ -24,7 +24,7 @@ export default iterateJsdoc(({
     objectFieldSeparator = 'comma',
     objectFieldSeparatorOptionalLinebreak = true,
     objectFieldSeparatorTrailingPunctuation = false,
-    propertyQuotes = null,
+    // propertyQuotes = null,
     separatorForSingleObjectField = false,
     stringQuotes = 'single',
     typeBracketSpacing = '',
@@ -277,19 +277,20 @@ export default iterateJsdoc(({
           break;
         }
 
-        case 'JsdocTypeProperty': {
-          const typeNode = /** @type {import('jsdoc-type-pratt-parser').PropertyResult} */ (nde);
+        // Only suitable for namepaths (and would need changes); see https://github.com/gajus/eslint-plugin-jsdoc/issues/1524
+        // case 'JsdocTypeProperty': {
+        //   const typeNode = /** @type {import('jsdoc-type-pratt-parser').PropertyResult} */ (nde);
 
-          if ((propertyQuotes ||
-            (typeof typeNode.value === 'string' && !(/\s/v).test(typeNode.value))) &&
-            typeNode.meta.quote !== (propertyQuotes ?? undefined)
-          ) {
-            typeNode.meta.quote = propertyQuotes ?? undefined;
-            errorMessage = `Inconsistent ${propertyQuotes} property quotes usage`;
-          }
+        //   if ((propertyQuotes ||
+        //     (typeof typeNode.value === 'string' && !(/\s/v).test(typeNode.value))) &&
+        //     typeNode.meta.quote !== (propertyQuotes ?? undefined)
+        //   ) {
+        //     typeNode.meta.quote = propertyQuotes ?? undefined;
+        //     errorMessage = `Inconsistent ${propertyQuotes} property quotes usage`;
+        //   }
 
-          break;
-        }
+        //   break;
+        // }
 
         case 'JsdocTypeStringValue': {
           const typeNode = /** @type {import('jsdoc-type-pratt-parser').StringValueResult} */ (nde);
@@ -369,21 +370,31 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           arrayBrackets: {
+            description: 'Determines how array generics are represented. Set to `angle` for the style `Array<type>` or `square` for the style `type[]`. Defaults to "square".',
             enum: [
               'angle',
               'square',
             ],
+            type: 'string',
           },
           enableFixer: {
+            description: 'Whether to enable the fixer. Defaults to `true`.',
             type: 'boolean',
           },
           genericDot: {
+            description: 'Boolean value of whether to use a dot before the angled brackets of a generic (e.g., `SomeType.<AnotherType>`). Defaults to `false`.',
             type: 'boolean',
           },
           objectFieldIndent: {
+            description: `A string indicating the whitespace to be added on each line preceding an
+object property-value field. Defaults to the empty string.`,
             type: 'string',
           },
           objectFieldQuote: {
+            description: `Whether and how object field properties should be quoted (e.g., \`{"a": string}\`).
+Set to \`single\`, \`double\`, or \`null\`. Defaults to \`null\` (no quotes unless
+required due to special characters within the field). Digits will be kept as is,
+regardless of setting (they can either represent a digit or a string digit).`,
             enum: [
               'double',
               'single',
@@ -391,6 +402,11 @@ export default iterateJsdoc(({
             ],
           },
           objectFieldSeparator: {
+            description: `For object properties, specify whether a "semicolon", "comma", "linebreak",
+"semicolon-and-linebreak", or "comma-and-linebreak" should be used after
+each object property-value pair.
+
+Defaults to \`"comma"\`.`,
             enum: [
               'comma',
               'comma-and-linebreak',
@@ -398,33 +414,55 @@ export default iterateJsdoc(({
               'semicolon',
               'semicolon-and-linebreak',
             ],
+            type: 'string',
           },
           objectFieldSeparatorOptionalLinebreak: {
+            description: `Whether \`objectFieldSeparator\` set to \`"semicolon-and-linebreak"\` or
+\`"comma-and-linebreak"\` should be allowed to optionally drop the linebreak.
+
+Defaults to \`true\`.`,
             type: 'boolean',
           },
           objectFieldSeparatorTrailingPunctuation: {
+            description: `If \`separatorForSingleObjectField\` is not in effect (i.e., if it is \`false\`
+or there are multiple property-value object fields present), this property
+will determine whether to add punctuation corresponding to the
+\`objectFieldSeparator\` (e.g., a semicolon) to the final object field.
+Defaults to \`false\`.`,
             type: 'boolean',
           },
-          propertyQuotes: {
-            enum: [
-              'double',
-              'single',
-              null,
-            ],
-          },
+          //           propertyQuotes: {
+          //             description: `Whether and how namepath properties should be quoted (e.g., \`ab."cd"."ef"\`).
+          // Set to \`single\`, \`double\`, or \`null\`. Defaults to \`null\` (no quotes unless
+          // required due to whitespace within the property).`,
+          //             enum: [
+          //               'double',
+          //               'single',
+          //               null,
+          //             ],
+          //           },
           separatorForSingleObjectField: {
+            description: `Whether to apply the \`objectFieldSeparator\` (e.g., a semicolon) when there
+is only one property-value object field present. Defaults to \`false\`.`,
             type: 'boolean',
           },
           stringQuotes: {
+            description: `How string literals should be quoted (e.g., \`"abc"\`). Set to \`single\`
+or \`double\`. Defaults to 'single'.`,
             enum: [
               'double',
               'single',
             ],
+            type: 'string',
           },
           typeBracketSpacing: {
+            description: `A string of spaces that will be added immediately after the type's initial
+curly bracket and immediately before its ending curly bracket. Defaults
+to the empty string.`,
             type: 'string',
           },
           unionSpacing: {
+            description: 'Determines the spacing to add to unions (`|`). Defaults to a single space (`" "`).',
             type: 'string',
           },
         },

package/src/rules/validTypes.js

@@ -392,7 +392,7 @@ export default iterateJsdoc(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Requires all types to be valid JSDoc or Closure compiler types without syntax errors.',
+      description: 'Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/valid-types.md#repos-sticky-header',
     },
     schema: [
@@ -401,6 +401,13 @@ export default iterateJsdoc(({
         properties: {
           allowEmptyNamepaths: {
             default: false,
+            description: `Set to \`false\` to bulk disallow
+empty name paths with namepath groups 2 and 4 (these might often be
+expected to have an accompanying name path, though they have some
+indicative value without one; these may also allow names to be defined
+in another manner elsewhere in the block); you can use
+\`settings.jsdoc.structuredTags\` with the \`required\` key set to "name" if you
+wish to require name paths on a tag-by-tag basis. Defaults to \`true\`.`,
             type: 'boolean',
           },
         },