chore: setup eslint-plugin-jsdoc to lint jsdoc

.eslintrc.cjs

@@ -6,6 +6,7 @@ module.exports = {
 	extends: [
 		"eslint:recommended",
 		"plugin:eslint-comments/recommended",
+		"plugin:jsdoc/recommended-error",
 		"plugin:regexp/recommended",
 		"prettier",
 	],
@@ -59,6 +60,7 @@ module.exports = {
 		"@typescript-eslint",
 		"deprecation",
 		"import",
+		"jsdoc",
 		"no-only-tests",
 		"regexp",
 		"simple-import-sort",
@@ -75,5 +77,46 @@ module.exports = {
 
 		// These on-by-default rules don't work well for this repo and we like them off.
 		"no-inner-declarations": "off",
+
+		// JSDoc rules
+		"jsdoc/check-indentation": "error",
+		"jsdoc/check-line-alignment": "error",
+		"jsdoc/check-tag-names": [
+			"error",
+			{
+				definedTags: ["category"],
+			},
+		],
+		"jsdoc/no-bad-blocks": "error",
+		"jsdoc/no-defaults": "error",
+		"jsdoc/require-asterisk-prefix": "error",
+		"jsdoc/require-description": "error",
+		"jsdoc/require-hyphen-before-param-description": "error",
+		"jsdoc/require-throws": "error",
+		"jsdoc/tag-lines": [
+			"error",
+			"never",
+			{
+				noEndLines: true,
+				tags: {
+					example: { lines: "always" },
+				},
+			},
+		],
+		"jsdoc/require-jsdoc": "off",
+		"jsdoc/require-param": "off",
+		"jsdoc/require-property": "off",
+		"jsdoc/require-returns": "off",
+		// Todo: pending a "recommended-typescript" config in eslint-plugin-jsdoc
+		// https://github.com/gajus/eslint-plugin-jsdoc/issues/615#issuecomment-1338669655
+		"jsdoc/no-types": "error",
+		"jsdoc/require-param-type": "off",
+		"jsdoc/require-property-type": "off",
+		"jsdoc/require-returns-type": "off",
+	},
+	settings: {
+		jsdoc: {
+			ignoreInternal: true,
+		},
 	},
 };

package.json

@@ -59,6 +59,7 @@
 		"eslint-plugin-deprecation": "^1.3.3",
 		"eslint-plugin-eslint-comments": "^3.2.0",
 		"eslint-plugin-import": "^2.27.5",
+		"eslint-plugin-jsdoc": "^40.0.1",
 		"eslint-plugin-jsonc": "^2.6.0",
 		"eslint-plugin-markdown": "^3.0.0",
 		"eslint-plugin-no-only-tests": "^3.1.0",

src/comments.ts

@@ -67,7 +67,6 @@ export type ForEachCommentCallback = (
  * Iterates over all comments owned by `node` or its children.
  *
  * @category Nodes - Other Utilities
- *
  * @example
  * ```ts
  * declare const node: ts.Node;

src/compilerOptions.ts

@@ -23,7 +23,6 @@ export type BooleanCompilerOptions = keyof {
  * This function only handles boolean flags.
  *
  * @category Compiler Options
- *
  * @example
  * ```ts
  * const options = {
@@ -115,7 +114,6 @@ export type StrictCompilerOption =
  * (except `strictPropertyInitialization`) have been enabled by `strict: true`.
  *
  * @category Compiler Options
- *
  * @example
  * ```ts
  * const optionsLenient = {

src/flags.ts

@@ -25,7 +25,6 @@ function isFlagSetOnObject(obj: { flags: number }, flag: number): boolean {
  * Test if the given node has the given `ModifierFlags` set.
  *
  * @category Nodes - Flag Utilities
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -46,7 +45,6 @@ export function isModifierFlagSet(
  * Test if the given node has the given `NodeFlags` set.
  *
  * @category Nodes - Flag Utilities
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -63,7 +61,6 @@ export const isNodeFlagSet: (node: ts.Node, flag: ts.NodeFlags) => boolean =
  * Test if the given node has the given `ObjectFlags` set.
  *
  * @category Nodes - Flag Utilities
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -84,7 +81,6 @@ export function isObjectFlagSet(
  * Test if the given node has the given `SymbolFlags` set.
  *
  * @category Nodes - Flag Utilities
- *
  * @example
  * ```ts
  * declare const symbol: ts.Symbol;
@@ -103,7 +99,6 @@ export const isSymbolFlagSet: (
  * Test if the given node has the given `TypeFlags` set.
  *
  * @category Nodes - Flag Utilities
- *
  * @example
  * ```ts
  * declare const type: ts.Type;

src/modifiers.ts

@@ -7,7 +7,6 @@ import * as ts from "typescript";
  * Test if the given iterable includes a modifier of any of the given kinds.
  *
  * @category Modifier Utilities
- *
  * @example
  * ```ts
  * declare const modifiers: ts.Modifier[];

src/nodes/typeGuards/compound.ts

@@ -32,7 +32,6 @@ export type ConstAssertionIdentifier = ts.Identifier & {
  * Test if a node is a {@link ConstAssertionExpression}.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -58,7 +57,6 @@ export function isConstAssertionExpression(
  * Test if a node is an `IterationStatement`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -89,7 +87,6 @@ export function isIterationStatement(
  * Test if a node is a `JSDocNamespaceDeclaration`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -115,7 +112,6 @@ export function isJSDocNamespaceDeclaration(
  * Test if a node is a `JsxTagNamePropertyAccess`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -149,7 +145,6 @@ export interface NamedDeclarationWithName extends ts.NamedDeclaration {
  * Test if a node is a {@link NamedDeclarationWithName}.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -176,7 +171,6 @@ export function isNamedDeclarationWithName(
  * Test if a node is a `NamespaceDeclaration`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -212,7 +206,6 @@ export type NumericOrStringLikeLiteral =
  * Test if a node is a {@link NumericOrStringLikeLiteral}.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -241,7 +234,6 @@ export function isNumericOrStringLikeLiteral(
  * Test if a node is a `PropertyAccessEntityNameExpression`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -267,7 +259,6 @@ export function isPropertyAccessEntityNameExpression(
  * Test if a node is a `SuperElementAccessExpression`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;
@@ -291,7 +282,6 @@ export function isSuperElementAccessExpression(
  * Test if a node is a `SuperPropertyAccessExpression`.
  *
  * @category Nodes - Type Guards
- *
  * @example
  * ```ts
  * declare const node: ts.Node;