v3: src/ is documented like api/ and shared/, and the reference covers the whole repository — the frontend had no module docs, JSDoc on some components and hooks and not on others, props typed inline in half the components and in private interfaces in the rest, // comments on declarations, and no return types on 147 exported functions, so deno doc --lint over src/ found 637 errors. The rule api/ follows is applied to every non-test module of src/: a /** … @module */ block, JSDoc on every export and every field of an exported interface, /** */ for declarations and // for notes, verbs for functions ("Renders…" for a component), parameters named in the prose, {@link} only for symbols in scope, and a page's JSDoc names its route and who may see it (App.tsx's module doc lists the route table). For deno doc to show them, every exported function states its return type: components React.JSX.Element (or | null, or a portal), memo and forwardRef components their exotic types, contexts React.Context<…>, and a hook returning several things a documented Use<Name>Result interface (useAuth, useRequiredAuth, useFading, useEmojiTrigger, useMentionAutocomplete, useDumpCardLink, usePlayRichContent; FeedCacheResult, YouTubePlaylistControls and UseApiFormReturn are renamed to match). Every component that takes props takes an exported, documented <Name>Props interface — the 64 inline prop types are lifted into one, DumpFeed gets DumpFeedProps extending MainFeedProps. React types go through the global React namespace: the four default imports of react are gone, since deno doc can't follow them. Two duplicates go too: useMentionAutocomplete's UserResult was shared/'s UserSuggestion, and JournalCard re-exported JournalShape for no one; i18n.ts no longer re-exports Lingui's i18n, which its three users now import from @lingui/core. deno task doc and doc:lint now take src/ (but its tests and the generated locales), the index page gains a Frontend section linking every module by layer and domain, mod.test.ts walks src/ as well, and the docs workflow runs on changes to src/. deno doc doesn't document npm packages, so it takes a type imported from one — react-hook-form's FieldValues in the form fields, frimousse's SkinTone — for a private one; doc:lint now goes through doc-lint.ts, which fails on every diagnostic but those, 25 of them. The README states the frontend's part of the rule. No behaviour changes; 205 backend and 628 frontend tests pass, and tsc, deno check and deno lint are clean.

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

src/pages/Dump.tsx

@@ -1,3 +1,9 @@
+/**
+ * A dump's page.
+ *
+ * @module
+ */
+
 import { useEffect, useState } from "react";
 import { Link, useLocation, useNavigate, useParams } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -40,12 +46,19 @@ import { Markdown } from "../components/editor/Markdown.tsx";
 import { CommentThread } from "../components/comment/CommentThread.tsx";
 import { Tooltip } from "../components/shared/Tooltip.tsx";
 
+/** The page's state: loading, failed, or loaded with the dump. */
 type DumpState =
   | { status: "loading" }
   | { status: "error"; error: string }
   | { status: "loaded"; dump: Dump };
 
-export function Dump() {
+/**
+ * Renders `/dumps/:selectedDump`, for anyone who may see the dump: its preview,
+ * title (editable in place by its poster), note, poster, categories and votes,
+ * the playlists holding it, related dumps and the comment thread, kept live by
+ * the socket.
+ */
+export function Dump(): React.JSX.Element {
   const { selectedDump } = useParams();
   const location = useLocation();
   const navigate = useNavigate();

src/pages/DumpEdit.tsx

@@ -1,3 +1,9 @@
+/**
+ * The dump editor.
+ *
+ * @module
+ */
+
 import { useEffect, useState } from "react";
 import { Link, useNavigate, useParams } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -38,12 +44,18 @@ import { TextField } from "../components/form/TextField.tsx";
 import { useApiForm } from "../hooks/form/useApiForm.ts";
 import { VisibilityToggle } from "../components/form/SegmentedField.tsx";
 
+/** The page's state: loading, failed, or loaded with the dump. */
 type DumpEditState =
   | { status: "loading" }
   | { status: "error"; error: string }
   | { status: "loaded"; dump: Dump };
 
-export function DumpEdit() {
+/**
+ * Renders `/dumps/:selectedDump/edit`, for a signed-in user: the dump's title,
+ * link or file, note, visibility and thumbnail to edit, its preview to refresh,
+ * and a delete button.
+ */
+export function DumpEdit(): React.JSX.Element {
   const { selectedDump } = useParams();
   const navigate = useNavigate();
   const { authFetch, token, mediaToken } = useRequiredAuth();
@@ -279,6 +291,7 @@ export function DumpEdit() {
   );
 }
 
+/** The props of {@link DumpEditForm}. */
 interface DumpEditFormProps {
   dump: Dump;
   preview: React.ReactNode;
@@ -292,6 +305,7 @@ interface DumpEditFormProps {
   onSaved: (dump: Dump) => void;
 }
 
+/** The form's fields. */
 interface EditValues {
   title: string;
   url: string;
@@ -300,6 +314,7 @@ interface EditValues {
   newFile: File | null;
 }
 
+/** Renders the dump's edit form. */
 function DumpEditForm({
   dump,
   preview,

src/pages/Index.tsx

@@ -1,3 +1,9 @@
+/**
+ * The feed page.
+ *
+ * @module
+ */
+
 import {
   useCallback,
   useEffect,
@@ -39,6 +45,7 @@ import { JournalFeed } from "../components/feed/JournalFeed.tsx";
 import { FollowedFeed } from "../components/feed/FollowedFeed.tsx";
 import { NotFound } from "./NotFound.tsx";
 
+/** The feed's state: loading, failed, or loaded with a page of dumps. */
 type DumpsState =
   | { status: "loading" }
   | { status: "error"; error: string }
@@ -50,12 +57,23 @@ type DumpsState =
     loadingMore: boolean;
   };
 
+/** The props of {@link Index}. */
+export interface IndexProps {
+  /** The category the feed is scoped to; every dump when undefined. */
+  categorySlug?: string;
+}
+
 /**
- * The shared feed page. `categorySlug` scopes it to a single category; when
- * absent it shows every dump. The router keys this component by scope, so each
- * category gets its own mount/fetch while switching feed tabs reuses it.
+ * Renders `/~/:feedTab` and `/:categorySlug/:feedTab`, for anyone: the shared
+ * feed page, its tabs (hot, new, journal, followed for a signed-in user), who's
+ * online, and new dumps as they arrive. `categorySlug` scopes it to a single
+ * category; when absent it shows every dump. The router keys this component by
+ * scope, so each category gets its own mount/fetch while switching feed tabs
+ * reuses it.
  */
-export function Index({ categorySlug }: { categorySlug?: string }) {
+export function Index(
+  { categorySlug }: IndexProps,
+): React.JSX.Element {
   const location = useLocation();
   const justDeletedId = (location.state as { deletedDumpId?: string } | null)
     ?.deletedDumpId;

src/pages/NotFound.tsx

@@ -1,10 +1,17 @@
+/**
+ * The page for a route that doesn't exist.
+ *
+ * @module
+ */
+
 import { Link } from "react-router";
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
 import { PageShell } from "../components/layout/PageShell.tsx";
 import { useDocumentTitle } from "../hooks/shared/useDocumentTitle.ts";
 
-export function NotFound() {
+/** Renders any unknown route: a 404 with a link home. */
+export function NotFound(): React.JSX.Element {
   useDocumentTitle(t`Page not found`);
   return (
     <PageShell centered>

src/pages/Notifications.tsx

@@ -1,4 +1,10 @@
-import React, { useEffect, useState } from "react";
+/**
+ * The notifications page.
+ *
+ * @module
+ */
+
+import { useEffect, useState } from "react";
 import { Link } from "react-router";
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
@@ -27,6 +33,9 @@ import { deserializeNotification } from "../utils/shared/deserialize.ts";
 import { PageShell } from "../components/layout/PageShell.tsx";
 import { expectOk, friendlyFetchError } from "../utils/shared/api.ts";
 
+/**
+ * The page's state: loading, failed, or loaded with a page of notifications.
+ */
 type State =
   // `arrived`: sent over the socket before the list came back — the list may
   // predate them, and the read-all that follows the load covers them anyway.
@@ -40,6 +49,7 @@ type State =
     loadingMore: boolean;
   };
 
+/** The icon a notification shows. */
 type NotifIconKind =
   | "upvote"
   | "follow"
@@ -49,6 +59,7 @@ type NotifIconKind =
   | "comment"
   | "like";
 
+/** Returns the icon for a notification of `type`. */
 function notifIconKind(type: Notification["type"]): NotifIconKind {
   switch (type) {
     case "dump_upvoted":
@@ -70,24 +81,28 @@ function notifIconKind(type: Notification["type"]): NotifIconKind {
   }
 }
 
+/** Renders the upvote glyph. */
 const UpvoteSvg = () => (
   <svg viewBox="0 0 10 10" width="11" height="11" fill="currentColor">
     <polygon points="5,1 9,9 1,9" />
   </svg>
 );
 
+/** Renders the follow glyph. */
 const FollowSvg = () => (
   <svg viewBox="0 0 10 10" width="10" height="10" fill="currentColor">
     <polygon points="2,1 9,5 2,9" />
   </svg>
 );
 
+/** Renders the like glyph. */
 const HeartSvg = () => (
   <svg viewBox="0 0 10 10" width="10" height="10" fill="currentColor">
     <path d="M5 9 C2 6.5 0 5 0 2.8 C0 1.2 1.2 0 2.6 0 C3.6 0 4.5 0.6 5 1.5 C5.5 0.6 6.4 0 7.4 0 C8.8 0 10 1.2 10 2.8 C10 5 8 6.5 5 9 Z" />
   </svg>
 );
 
+/** Renders the icon of a notification of `type`. */
 function NotifIcon({ type }: { type: Notification["type"] }) {
   const kind = notifIconKind(type);
   const glyphs: Record<NotifIconKind, React.ReactNode> = {
@@ -106,6 +121,7 @@ function NotifIcon({ type }: { type: Notification["type"] }) {
   );
 }
 
+/** Returns where notification `n` leads. */
 function notificationLink(n: Notification): string {
   const data = n.data as NotificationData;
   switch (n.type) {
@@ -140,6 +156,7 @@ function notificationLink(n: Notification): string {
   }
 }
 
+/** Returns the sentence notification `n` shows. */
 function notificationContent(n: Notification): React.ReactNode {
   const data = n.data as NotificationData;
   switch (n.type) {
@@ -231,16 +248,19 @@ function notificationContent(n: Notification): React.ReactNode {
   }
 }
 
+/** Returns how long ago `date` was within a week, else its day. */
 function timeAgo(date: Date): string {
   const abs = Math.abs(Date.now() - date.getTime()) / 1000;
   if (abs < 7 * 86400) return relativeTime(date);
   return date.toLocaleDateString(undefined, { month: "short", day: "numeric" });
 }
 
+/** Returns the local midnight that starts the day of `d`, in epoch ms. */
 function startOfDay(d: Date): number {
   return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
 }
 
+/** Returns `items` grouped under Today, Yesterday and Earlier. */
 function groupByDate(
   items: Notification[],
 ): { label: string; items: Notification[] }[] {
@@ -263,7 +283,12 @@ function groupByDate(
     .map((label) => ({ label, items: buckets[label] }));
 }
 
-export function Notifications() {
+/**
+ * Renders `/notifications`, for a signed-in user: their notifications by day,
+ * new ones as they arrive, loading more on demand. Opening the page marks them
+ * all read.
+ */
+export function Notifications(): React.JSX.Element {
   useDocumentTitle(t`Notifications`);
   const { authFetch } = useAuth();
   const { clearUnreadNotifications, lastNotification } = useWS();

src/pages/PlaylistDetail.tsx

@@ -1,3 +1,9 @@
+/**
+ * A playlist's page.
+ *
+ * @module
+ */
+
 import {
   useCallback,
   useEffect,
@@ -47,12 +53,19 @@ import { FormError } from "../components/form/FormError.tsx";
 import { SubmitButton } from "../components/form/SubmitButton.tsx";
 import { useApiForm } from "../hooks/form/useApiForm.ts";
 
+/** The page's state: loading, failed, or loaded with the playlist. */
 type LoadState =
   | { status: "loading" }
   | { status: "error"; error: string }
   | { status: "loaded"; playlist: PlaylistWithDumps };
 
-export function PlaylistDetail() {
+/**
+ * Renders `/playlists/:playlistId` (an id or a slug), for anyone who may see
+ * the playlist: its cover, title, description and owner, a follow button, and
+ * its dumps, kept live by the socket. Its owner or a moderator can edit or
+ * delete it, drag its dumps into a new order, and remove one (with an undo).
+ */
+export function PlaylistDetail(): React.JSX.Element {
   const { playlistId } = useParams<{ playlistId: string }>();
   const navigate = useNavigate();
   const { user, authFetch, token, mediaToken } = useAuth();
@@ -801,6 +814,7 @@ export function PlaylistDetail() {
   );
 }
 
+/** The props of {@link PlaylistEditForm}. */
 interface PlaylistEditFormProps {
   playlist: PlaylistWithDumps;
   onCancel: () => void;
@@ -808,6 +822,7 @@ interface PlaylistEditFormProps {
   onSaved: (playlist: Playlist) => void;
 }
 
+/** The form's fields. */
 interface EditValues {
   title: string;
   description: string;
@@ -815,6 +830,9 @@ interface EditValues {
   image: File | null;
 }
 
+/**
+ * Renders the playlist's edit form: title, description, visibility and cover.
+ */
 function PlaylistEditForm(
   { playlist, onCancel, onRequestDelete, onSaved }: PlaylistEditFormProps,
 ) {

src/pages/ResetPassword.tsx

@@ -1,3 +1,9 @@
+/**
+ * The password reset page.
+ *
+ * @module
+ */
+
 import { useState } from "react";
 import { Link, useNavigate, useSearchParams } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -14,12 +20,17 @@ import { SubmitButton } from "../components/form/SubmitButton.tsx";
 import { TextField } from "../components/form/TextField.tsx";
 import { useApiForm } from "../hooks/form/useApiForm.ts";
 
+/** The form's fields. */
 interface Values {
   newPassword: string;
   confirm: string;
 }
 
-export function ResetPassword() {
+/**
+ * Renders `/reset-password?token=`, for anyone holding a reset link: the form
+ * that sets a new password.
+ */
+export function ResetPassword(): React.JSX.Element {
   useDocumentTitle(t`Reset password`);
   const [params] = useSearchParams();
   const navigate = useNavigate();

src/pages/RestrictedGuest.tsx

@@ -1,8 +1,25 @@
+/**
+ * The guard of the routes for the signed out.
+ *
+ * @module
+ */
+
 import { Navigate } from "react-router";
 
 import { useAuth } from "../hooks/auth/useAuth.ts";
 
-export function RestrictedGuest({ children }: { children: React.ReactNode }) {
+/** The props of {@link RestrictedGuest}. */
+export interface RestrictedGuestProps {
+  /** The page. */
+  children: React.ReactNode;
+}
+
+/**
+ * Renders `children` when no one is signed in, and redirects home otherwise.
+ */
+export function RestrictedGuest(
+  { children }: RestrictedGuestProps,
+): React.JSX.Element {
   const { user } = useAuth();
 
   return user ? <Navigate to="/" /> : <>{children}</>;

src/pages/RestrictedLoggedIn.tsx

@@ -1,10 +1,26 @@
+/**
+ * The guard of the routes for the signed in.
+ *
+ * @module
+ */
+
 import { Navigate } from "react-router";
 
 import { useAuth } from "../hooks/auth/useAuth.ts";
 
+/** The props of {@link RestrictedLoggedIn}. */
+export interface RestrictedLoggedInProps {
+  /** The page. */
+  children: React.ReactNode;
+}
+
+/**
+ * Renders `children` when someone is signed in, and redirects to the login page
+ * otherwise.
+ */
 export function RestrictedLoggedIn(
-  { children }: { children: React.ReactNode },
-) {
+  { children }: RestrictedLoggedInProps,
+): React.JSX.Element {
   const { user } = useAuth();
 
   return user ? <>{children}</> : <Navigate to="/login" />;

src/pages/Search.tsx

@@ -1,3 +1,9 @@
+/**
+ * The search results page.
+ *
+ * @module
+ */
+
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Link, useSearchParams } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -24,9 +30,12 @@ import type { Wire } from "../../shared/api.ts";
 import { DEFAULT_PAGE_SIZE, SEARCH_URL } from "../config/api.ts";
 import { friendlyFetchError } from "../utils/shared/api.ts";
 
+/** The result tabs. */
 const SEARCH_TABS = ["dumps", "users", "playlists"] as const;
+/** One of the {@link SEARCH_TABS}. */
 type Tab = (typeof SEARCH_TABS)[number];
 
+/** The page's state: idle, loading, failed, or loaded with the results. */
 type SearchState =
   | { status: "idle" }
   | { status: "loading" }
@@ -45,7 +54,11 @@ type SearchState =
     playlists: Playlist[];
   };
 
-export function Search() {
+/**
+ * Renders `/search?q=` and `/search/~/:searchTab`, for anyone: the dumps (a
+ * page at a time), users and playlists matching the query, one tab each.
+ */
+export function Search(): React.JSX.Element {
   useDocumentTitle(t`Search`);
   const [searchParams] = useSearchParams();
   const q = searchParams.get("q") ?? "";

src/pages/UserDumps.tsx

@@ -1,3 +1,9 @@
+/**
+ * A user's full list of dumps.
+ *
+ * @module
+ */
+
 import { useState } from "react";
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
@@ -15,7 +21,11 @@ import { ProfileSubpageHeader } from "../components/profile/ProfileSubpageHeader
 import { PageShell } from "../components/layout/PageShell.tsx";
 import { PageError } from "../components/layout/PageError.tsx";
 
-export function UserDumps() {
+/**
+ * Renders `/users/:username/dumps`, for anyone: every dump of the user the
+ * viewer may see, a page at a time, kept live by the socket.
+ */
+export function UserDumps(): React.JSX.Element {
   const { username } = useParams();
   const { user: me } = useAuth();
   const { voteCounts, myVotes, lastDumpEvent, castVote, removeVote } = useWS();

src/pages/UserLogin.tsx

@@ -1,3 +1,9 @@
+/**
+ * The sign-in page.
+ *
+ * @module
+ */
+
 import { useState } from "react";
 import { useNavigate } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -18,16 +24,22 @@ import { SubmitButton } from "../components/form/SubmitButton.tsx";
 import { TextField } from "../components/form/TextField.tsx";
 import { useApiForm } from "../hooks/form/useApiForm.ts";
 
+/** The sign-in form's fields. */
 interface LoginValues {
   username: string;
   password: string;
 }
 
+/** The reset request form's fields. */
 interface ResetValues {
   email: string;
 }
 
-export function UserLogin() {
+/**
+ * Renders `/login`, for the signed out: the sign-in form, and a way to ask for
+ * a password reset link.
+ */
+export function UserLogin(): React.JSX.Element {
   useDocumentTitle(t`Log in`);
   const navigate = useNavigate();
   const { login } = useAuth();
@@ -98,6 +110,10 @@ export function UserLogin() {
   );
 }
 
+/**
+ * Renders the form that emails a password reset link. The answer is the same
+ * whether or not the address is known.
+ */
 function ResetRequestPanel() {
   const [sent, setSent] = useState(false);
   const form = useApiForm<ResetValues>({ defaultValues: { email: "" } });

src/pages/UserPlaylists.tsx

@@ -1,3 +1,9 @@
+/**
+ * A user's full lists of playlists.
+ *
+ * @module
+ */
+
 import {
   useCallback,
   useEffect,
@@ -35,6 +41,7 @@ import { PageShell } from "../components/layout/PageShell.tsx";
 import { PageError } from "../components/layout/PageError.tsx";
 import { ErrorCard } from "../components/shared/ErrorCard.tsx";
 
+/** A paginated list of playlists. */
 interface PlaylistFeed {
   items: Playlist[];
   hasMore: boolean;
@@ -42,6 +49,7 @@ interface PlaylistFeed {
   loadingMore: boolean;
 }
 
+/** The page's state: loading, failed, or loaded with both lists. */
 type State =
   | { status: "loading" }
   | { status: "error"; error: string }
@@ -52,11 +60,17 @@ type State =
     followed: PlaylistFeed;
   };
 
+/** Returns the first page of a list. */
 function initialFeed(items: Playlist[], hasMore: boolean): PlaylistFeed {
   return { items, hasMore, page: 1, loadingMore: false };
 }
 
-export function UserPlaylists() {
+/**
+ * Renders `/users/:username/playlists`, for anyone: the playlists the user made
+ * (the private ones only to them) and those they follow, a page at a time, kept
+ * live by the socket; the owner can make and delete playlists.
+ */
+export function UserPlaylists(): React.JSX.Element {
   const { username } = useParams();
   const { user: me, authFetch, token } = useAuth();
 

src/pages/UserPublicProfile.tsx

@@ -1,4 +1,10 @@
-import React, {
+/**
+ * A user's profile.
+ *
+ * @module
+ */
+
+import {
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -71,9 +77,10 @@ import { SubmitButton } from "../components/form/SubmitButton.tsx";
 import { useApiForm } from "../hooks/form/useApiForm.ts";
 
 /**
- * Own-profile action row: "Invite someone" then `children` (log out). The
- * invite button toggles a panel below the row holding a fresh single-use link;
- * the panel eases in like the inline editors and takes the row's width.
+ * Renders the own-profile action row: "Invite someone" then `children` (log
+ * out). The invite button toggles a panel below the row holding a fresh
+ * single-use link; the panel eases in like the inline editors and takes the
+ * row's width.
  */
 function ProfileOwnActions({ children }: { children: React.ReactNode }) {
   const { authFetch } = useAuth();
@@ -172,6 +179,7 @@ function ProfileOwnActions({ children }: { children: React.ReactNode }) {
   );
 }
 
+/** A paginated list. */
 interface PaginatedList<T> {
   items: T[];
   hasMore: boolean;
@@ -179,10 +187,12 @@ interface PaginatedList<T> {
   loadingMore: boolean;
 }
 
+/** Returns the first page of a list. */
 function initialList<T>(items: T[], hasMore: boolean): PaginatedList<T> {
   return { items, hasMore, page: 1, loadingMore: false };
 }
 
+/** The profile's state: loading, failed, or loaded with its lists. */
 type ProfileState =
   | { status: "loading" }
   | { status: "error"; error: string }
@@ -194,6 +204,7 @@ type ProfileState =
     playlists: PaginatedList<Playlist>;
   };
 
+/** The followed tab's state, null until it is opened. */
 type FollowedState =
   | null
   | { status: "loading" }
@@ -204,13 +215,16 @@ type FollowedState =
     playlists: PaginatedList<Playlist>;
   };
 
+/** The invitees tab's state, null until it is opened. */
 type InviteTreeState =
   | null
   | { status: "loading" }
   | { status: "error"; error: string }
   | { status: "loaded"; entries: Invitee[] };
 
+/** An invitee, with those they invited. */
 type InviteTreeNode = Invitee & { children: InviteTreeNode[] };
+/** The profile's tabs. */
 const PROFILE_TABS = [
   "dumps",
   "playlists",
@@ -219,8 +233,10 @@ const PROFILE_TABS = [
   "settings",
   "manage",
 ] as const;
+/** One of the {@link PROFILE_TABS}. */
 type ProfileTab = (typeof PROFILE_TABS)[number];
 
+/** Returns the invitees of `parentId` among `entries`, each with theirs. */
 function buildInviteTree(
   entries: Invitee[],
   parentId: string,
@@ -230,7 +246,16 @@ function buildInviteTree(
     .map((e) => ({ ...e, children: buildInviteTree(entries, e.id) }));
 }
 
-export function UserPublicProfile() {
+/**
+ * Renders `/users/:username` and `/users/:username/~/:profileTab`, for anyone:
+ * the user's avatar, name, role and description, and their dumps, playlists,
+ * follows and invitees, one tab each. On their own profile a user can change
+ * their avatar, description and email, invite someone, and set the theme,
+ * sounds, default feed tab and password. The manage tab changes another user's
+ * role, with `user:manage`, or on one's own profile manages the categories,
+ * with `category:manage`.
+ */
+export function UserPublicProfile(): React.JSX.Element {
   const { username } = useParams();
   const navigate = useNavigate();
   const { user: me, authFetch, updateSession, logout, token } = useAuth();
@@ -1428,6 +1453,7 @@ export function UserPublicProfile() {
 
 // ── Plain dump list ──────────────────────────────────────────────────────────
 
+/** Renders a list of dump cards. */
 function DumpList(
   {
     title,
@@ -1504,6 +1530,7 @@ function DumpList(
 
 // ── Upvoted list: fades items out when votes are removed ─────────────────────
 
+/** Renders the upvoted list, fading items out when their votes are removed. */
 function UpvotedDumpList(
   {
     title,
@@ -1641,6 +1668,7 @@ function UpvotedDumpList(
 
 // ── Invite tree ──────────────────────────────────────────────────────────────
 
+/** Renders the invite tree. */
 function InviteTreeList({ nodes }: { nodes: InviteTreeNode[] }) {
   return (
     <ul className="invite-tree">
@@ -1667,6 +1695,7 @@ function InviteTreeList({ nodes }: { nodes: InviteTreeNode[] }) {
 
 // ── Followed user card ───────────────────────────────────────────────────────
 
+/** Renders a followed user. */
 function FollowedUserCard({ user }: { user: PublicUser }) {
   return (
     <li className="followed-user-card">
@@ -1688,14 +1717,17 @@ function FollowedUserCard({ user }: { user: PublicUser }) {
   );
 }
 
+/** The roles, with their labels. */
 const ROLE_OPTIONS: { value: Role; label: React.ReactNode }[] = [
   { value: "user", label: <Trans>User</Trans> },
   { value: "moderator", label: <Trans>Moderator</Trans> },
   { value: "admin", label: <Trans>Admin</Trans> },
 ];
 
-// Role badge shown next to the username. The default "user" role is implicit,
-// so only elevated roles get a chip to avoid labelling every profile.
+/**
+ * Renders the role badge shown next to the username. The default "user" role is
+ * implicit, so only elevated roles get a chip to avoid labelling every profile.
+ */
 function RoleChip({ role }: { role: Role }) {
   if (role === "user") return null;
   const label = ROLE_OPTIONS.find((o) => o.value === role)?.label;
@@ -1706,14 +1738,17 @@ function RoleChip({ role }: { role: Role }) {
   );
 }
 
+/** The props of {@link RoleSwitcher}. */
 interface RoleSwitcherProps {
   userId: string;
   currentRole: Role;
   onSaved: (role: Role) => void;
 }
 
-// Segmented role control (matches the dump-visibility toggle style), gated
-// behind the user:manage permission by its caller.
+/**
+ * Renders the segmented role control (matches the dump-visibility toggle
+ * style), gated behind the user:manage permission by its caller.
+ */
 function RoleSwitcher({ userId, currentRole, onSaved }: RoleSwitcherProps) {
   const { authFetch } = useAuth();
   const [saving, setSaving] = useState(false);
@@ -1766,12 +1801,14 @@ function RoleSwitcher({ userId, currentRole, onSaved }: RoleSwitcherProps) {
   );
 }
 
+/** The props of {@link EmailEditor}. */
 interface EmailEditorProps {
   initialEmail: string;
   onCancel: () => void;
   onSaved: (email: string) => void;
 }
 
+/** Renders the inline editor of the user's email address. */
 function EmailEditor({ initialEmail, onCancel, onSaved }: EmailEditorProps) {
   const { authFetch } = useAuth();
   const form = useApiForm<{ email: string }>({
@@ -1829,12 +1866,14 @@ function EmailEditor({ initialEmail, onCancel, onSaved }: EmailEditorProps) {
   );
 }
 
+/** The props of {@link DescriptionEditor}. */
 interface DescriptionEditorProps {
   initialDescription: string;
   onCancel: () => void;
   onSaved: (description: string | undefined) => void;
 }
 
+/** Renders the inline editor of the user's description. */
 function DescriptionEditor(
   { initialDescription, onCancel, onSaved }: DescriptionEditorProps,
 ) {

src/pages/UserRegister.tsx

@@ -1,3 +1,9 @@
+/**
+ * The sign-up page.
+ *
+ * @module
+ */
+
 import { useEffect, useState } from "react";
 import { Link, useNavigate, useSearchParams } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -19,18 +25,24 @@ import { SubmitButton } from "../components/form/SubmitButton.tsx";
 import { TextField } from "../components/form/TextField.tsx";
 import { useApiForm } from "../hooks/form/useApiForm.ts";
 
+/** The invite's state: being checked, invalid, or valid. */
 type TokenState =
   | { status: "checking" }
   | { status: "invalid" }
   | { status: "valid" };
 
+/** The form's fields. */
 interface Values {
   username: string;
   email: string;
   password: string;
 }
 
-export function UserRegister() {
+/**
+ * Renders `/register?token=`, for the signed out holding an invite: the invite
+ * is checked, then the sign-up form, which signs the new user in.
+ */
+export function UserRegister(): React.JSX.Element {
   useDocumentTitle(t`Register`);
   const navigate = useNavigate();
   const { login } = useAuth();

src/pages/UserUpvoted.tsx

@@ -1,3 +1,9 @@
+/**
+ * A user's full list of upvoted dumps.
+ *
+ * @module
+ */
+
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Link, useParams } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -17,7 +23,12 @@ import { ProfileSubpageHeader } from "../components/profile/ProfileSubpageHeader
 import { PageShell } from "../components/layout/PageShell.tsx";
 import { PageError } from "../components/layout/PageError.tsx";
 
-export function UserUpvoted() {
+/**
+ * Renders `/users/:username/upvoted`, for anyone: every dump the user upvoted
+ * that the viewer may see, a page at a time; on one's own list a withdrawn vote
+ * fades its dump out.
+ */
+export function UserUpvoted(): React.JSX.Element {
   const { username } = useParams();
   const { user: me } = useAuth();
   const { voteCounts, myVotes, lastVoteEvent, castVote, removeVote } = useWS();