v3: comments say what the code can't — the documentation pass wanted JSDoc on every export and every field of an exported interface, which filled the code with restatements ("The dump.", "Whether it is loading.", "The props of X.", "Renders the X.") and module docs that told a reader nothing ("The hot and new feeds, and the props every main feed of the index takes."); some were wrong as well as vague. Every comment in api/, shared/ and src/ is rewritten under one rule, now stated in the README's "Comments" section: every module and export still has a JSDoc, and it gives context (who uses it and where), usage (what a caller must know: a precondition, what it leaves to the caller, a side effect) or its place in the chain (where its input comes from, where its output goes); a field, parameter, private function or local gets one only when it adds to its parent's, and context about a whole type goes on the type; a type's doc is phrased from the value's side ("Returned to Y by X when Z", "Passed to Y by X"); full sentences, as short as they can be, no label-colon-list; // goes wherever the code isn't obvious and says why, and the section banners and narration go. Every claim was checked against the code, which turned up some forty comments that were wrong: DumpCard's claimed it was only used by the hot and new feeds, the WebSocket welcome claimed to be a socket's first message (presence comes first), UpdateUserRequest said null removes a description (it keeps it), deletedDumpIds leaves out that it also holds dumps made private, THEME_COLOR claimed to mirror index.html's, and the like. The routers' JSDoc now says where they are mounted and what becomes of a thrown APIException. doc-lint.ts lets a field without a doc through; a module or export without one still fails. No code changes; 204 backend and 628 frontend tests pass, and doc:lint, deno check, deno lint and tsc are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/App.tsx

@@ -1,25 +1,29 @@
 /**
- * The app: its providers and its routes.
+ * Renders the whole app, its providers around its routes. `main.tsx` mounts
+ * it. The routes, in the order they match, are these.
  *
- * - `/` — redirects to the default feed tab.
- * - `/~/:feedTab` — the feed of every dump ({@link Index}).
- * - `/:categorySlug/:feedTab` — a category's feed; `/:categorySlug` redirects
- *   to
- * its default tab.
- * - `/dumps/:selectedDump` — a dump ({@link Dump}); `/edit` — its editor
- * ({@link DumpEdit}), signed in.
- * - `/login`, `/register` — sign-in and sign-up ({@link UserLogin},
- * {@link UserRegister}), signed out.
- * - `/reset-password` — a new password from a reset link ({@link
- *   ResetPassword}).
- * - `/users/:username` and `/users/:username/~/:profileTab` — a profile
- * ({@link UserPublicProfile}); `/dumps`, `/upvoted`, `/playlists` — its full
- * lists ({@link UserDumps}, {@link UserUpvoted}, {@link UserPlaylists}).
- * - `/playlists/:playlistId` — a playlist ({@link PlaylistDetail}).
- * - `/search` and `/search/~/:searchTab` — search results ({@link Search}).
- * - `/notifications` — the user's notifications ({@link Notifications}), signed
- * in.
- * - anything else — {@link NotFound}.
+ * - `/` redirects to the viewer's default feed tab, keeping the query string.
+ * - `/~/:feedTab` is the feed of every dump (`Index`).
+ * - `/dumps/:selectedDump` is a dump (`Dump`), and its `/edit` the dump's
+ *   editor (`DumpEdit`), signed in only.
+ * - `/register` and `/login` sign up and sign in (`UserRegister`,
+ *   `UserLogin`), signed out only.
+ * - `/users/:username` and `/users/:username/~/:profileTab` are a profile
+ *   (`UserPublicProfile`). Its `/dumps`, `/upvoted` and `/playlists` are its
+ *   full lists (`UserDumps`, `UserUpvoted`, `UserPlaylists`).
+ * - `/playlists/:playlistId` is a playlist (`PlaylistDetail`).
+ * - `/search` and `/search/~/:searchTab` are the search results (`Search`).
+ * - `/reset-password` sets a new password from an emailed link
+ *   (`ResetPassword`).
+ * - `/notifications` lists the user's notifications (`Notifications`), signed
+ *   in only.
+ * - `/:categorySlug/:feedTab` is a category's feed (`Index`), and
+ *   `/:categorySlug` redirects to its default tab.
+ * - Any other path is `NotFound`.
+ *
+ * The pages not marked are open to anyone. Every page is loaded with its
+ * route. Since category slugs share the root with the other routes, the server
+ * reserves those routes' names as slugs.
  *
  * @module
  */
@@ -53,7 +57,6 @@ import { ChatFab } from "./components/layout/ChatFab.tsx";
 
 import "./App.css";
 
-/** The feed page, loaded with its route; so is every page below. */
 const Index = lazy(() =>
   import("./pages/Index.tsx").then((m) => ({ default: m.Index }))
 );
@@ -108,8 +111,8 @@ const NotFound = lazy(() =>
 );
 
 /**
- * Returns the default feed tab for the current viewer ("followed" needs a
- * session).
+ * Returns the viewer's default feed tab, from their settings. A signed-out
+ * viewer never gets "followed", which needs a session.
  */
 function useResolvedDefaultTab() {
   const { user } = useAuth();
@@ -118,9 +121,9 @@ function useResolvedDefaultTab() {
 }
 
 /**
- * Redirects `/` to the default feed tab. The query string has to survive the
- * hop: the Web Share Target posts to "/", so an Android share arrives here as
- * `/?share_url=…` and the feed below is the only thing that can act on it.
+ * Redirects `/` to the default feed tab. The query string must survive: the
+ * web app manifest's share target opens `/?share_url=…` for an Android share,
+ * and only the feed acts on it.
  */
 function IndexRedirect() {
   const { search } = useLocation();
@@ -140,9 +143,9 @@ function CategoryRedirect() {
 }
 
 /**
- * Renders the feed of `/~/:feedTab` (all) and `/:categorySlug/:feedTab` alike.
- * Keying by scope remounts the feed when switching categories so it refetches,
- * while switching tabs within a scope keeps it mounted (client-side re-sort).
+ * Renders the feed of `/~/:feedTab` and `/:categorySlug/:feedTab` alike. The
+ * key remounts the feed on a change of category, so that it refetches, and
+ * keeps it mounted on a change of tab, which sorts on the client.
  */
 function ScopedIndex() {
   const { categorySlug } = useParams();
@@ -217,8 +220,9 @@ function AppRoutes() {
 }
 
 /**
- * Renders the app: the theme, session, player, socket, follow and category
- * providers around the router, the chat, the routes and the global player.
+ * Renders the app. The player, socket, follow and chat providers read the
+ * session, and `ChatProvider` reads the URL, so it sits inside the router.
+ * `GlobalPlayer` sits outside the routes, so playback survives navigation.
  */
 export function App(): React.JSX.Element {
   return (