chore(lint): lint JSDoc and run ESLint in npm run lint

.github/workflows/CI.yml

@@ -48,8 +48,6 @@ jobs:
       run: npm run typecheck
     - name: 🔤 Spell Check
       run: npm run spellcheck
-    - name: 🧹 ESLint
-      run: npm run eslint
     # Docusaurus derives a heading's anchor from its text, so renaming a
     # heading moves the anchor and breaks every inbound link. An explicit id
     # survives the rename, and lets a translation keep the English anchor

CONTRIBUTING.md

@@ -88,7 +88,7 @@ This builds the English site only, the same build as a Vercel preview.
 
 ### Linting Documentation
 
-This repository uses [Prettier](https://prettier.io/), an opinionated code formatter, in order to keep consistent formatting throughout the documentation. Run the following command to automatically fix all formatting, and then push any changes:
+This repository uses [ESLint](https://eslint.org/) to catch markup the build cannot check, such as raw links and headings and misaligned JSDoc comments, and [Prettier](https://prettier.io/), an opinionated code formatter, to keep consistent formatting throughout the documentation. Run the following command to report ESLint errors and automatically fix all formatting, and then push any changes:
 
 ```
 npm run lint
@@ -230,7 +230,7 @@ The build only checks links and anchors that go through Markdown or these compon
 Markup inside code samples is exempt, since it's example code rather than part of the page. CI fails on a raw `<a>` or heading anywhere else. To check before pushing, run:
 
 ```
-npm run eslint
+npm run lint
 ```
 
 ### Playgrounds

eslint.config.mjs

@@ -1,5 +1,6 @@
 import docusaurus from '@docusaurus/eslint-plugin';
 import tsParser from '@typescript-eslint/parser';
+import jsdoc from 'eslint-plugin-jsdoc';
 import * as mdx from 'eslint-plugin-mdx';
 
 import versions from './versions.json' with { type: 'json' };
@@ -38,6 +39,18 @@ export default [
     plugins: { '@docusaurus': docusaurus },
     rules,
   },
+  {
+    // Keeps every line of a JSDoc block starting with an aligned ` * `.
+    files: ['src/**/*.{js,jsx,ts,tsx}'],
+    // An ejected swizzle that disables a rule from a plugin this repo does not install.
+    ignores: ['src/theme/prism-include-languages.ts'],
+    languageOptions: { parser: tsParser },
+    plugins: { jsdoc },
+    rules: {
+      'jsdoc/check-alignment': 'error',
+      'jsdoc/require-asterisk-prefix': 'error',
+    },
+  },
   {
     ...mdx.flat,
     // Code samples are page content, not markup, so they are not linted.