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/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,
 ) {