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/components/dump/DumpCard.tsx

@@ -1,3 +1,9 @@
+/**
+ * A dump, as a card in the hot and new feeds.
+ *
+ * @module
+ */
+
 import { memo } from "react";
 import { Link } from "react-router";
 import { Plural, Trans } from "@lingui/react/macro";
@@ -19,20 +25,36 @@ import { VoteButton } from "../social/VoteButton.tsx";
 import { Markdown } from "../editor/Markdown.tsx";
 import { Tooltip } from "../shared/Tooltip.tsx";
 
-interface DumpCardProps {
+/** The props of {@link DumpCard}. */
+export interface DumpCardProps {
+  /** The dump. */
   dump: Dump;
+  /** Its live vote count. */
   voteCount: number;
+  /** Whether the user upvoted it. */
   voted: boolean;
+  /** Whether the user may vote (signed in). */
   canVote: boolean;
+  /** Upvotes dump `id`; `shownCount` is the count on screen. */
   castVote: (id: string, shownCount?: number) => void;
+  /** Withdraws the vote on dump `id`; `shownCount` is the count on screen. */
   removeVote: (id: string, shownCount?: number) => void;
+  /** An extra class. */
   className?: string;
+  /** Whether the viewer posted it: no unread dot. */
   isOwner?: boolean;
 }
 
-// Memoized: a feed re-renders on every live event (a vote anywhere, a new
-// dump), and a card whose props haven't changed has nothing to redraw.
-export const DumpCard = memo(function DumpCard(
+/**
+ * Renders a dump as a card: its preview (playable where it can be), title,
+ * note, categories, poster, age, comment count and vote button, with an unread
+ * dot until it is opened. The card opens the dump. Memoized: a feed re-renders
+ * on every live event (a vote anywhere, a new dump), and a card whose props
+ * haven't changed has nothing to redraw.
+ */
+export const DumpCard: React.MemoExoticComponent<
+  (props: DumpCardProps) => React.JSX.Element
+> = memo(function DumpCard(
   { dump, voteCount, voted, canVote, castVote, removeVote, className, isOwner }:
     DumpCardProps,
 ) {

src/components/dump/FilePreview.tsx

@@ -1,3 +1,10 @@
+/**
+ * The preview of an uploaded file: an image, a player, a PDF or a download
+ * link.
+ *
+ * @module
+ */
+
 import { useContext, useEffect, useState } from "react";
 import type { Dump } from "../../../shared/dump.ts";
 import { formatBytes } from "../../utils/shared/format.ts";
@@ -25,14 +32,18 @@ import {
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
 
-interface FilePreviewProps {
+/** The props of {@link FilePreview}. */
+export interface FilePreviewProps {
+  /** The file dump. */
   dump: Dump;
+  /** Whether to render the small thumbnail of a card. */
   compact?: boolean;
+  /** Whether audio and video play in the global player rather than inline. */
   global?: boolean;
 }
 
 /**
- * Build the global-player item for an uploaded file, so every entry point
+ * Returns the global-player item for an uploaded file, so every entry point
  * (compact cards, the detail page, the waveform) puts the same title, artwork
  * and subtitle in the player header.
  *
@@ -58,8 +69,11 @@ function filePlayerItem(
   };
 }
 
-// Waveform preview for the dump detail page — routes to global player,
-// reflects live play state and position from PlayerContext/PlayerTimeContext.
+/**
+ * Renders the waveform preview for the dump detail page — routes to the global
+ * player, reflects live play state and position from PlayerContext and
+ * PlayerTimeContext.
+ */
 function AudioFilePreview(
   { fileUrl, mime, dump }: { fileUrl: string; mime: string; dump: Dump },
 ) {
@@ -160,6 +174,7 @@ function AudioFilePreview(
   );
 }
 
+/** Renders a video's still, or `fallback` when it fails to load. */
 function VideoThumb({ src, fallback }: { src: string; fallback: string }) {
   const [failed, setFailed] = useState(false);
   if (failed) {
@@ -177,6 +192,7 @@ function VideoThumb({ src, fallback }: { src: string; fallback: string }) {
   );
 }
 
+/** Returns the icon for a file of type `mime`. */
 function mimeIcon(mime: string): string {
   if (mime.startsWith("video/")) return "🎬";
   if (mime.startsWith("audio/")) return "🎵";
@@ -185,9 +201,14 @@ function mimeIcon(mime: string): string {
   return "📁";
 }
 
+/**
+ * Renders an uploaded file by its type: compact, a thumbnail or icon that plays
+ * it; full size, the image, a player (or a play button for the global player),
+ * the PDF, or a download link.
+ */
 export function FilePreview(
   { dump, compact = false, global: useGlobal = false }: FilePreviewProps,
-) {
+): React.JSX.Element {
   const { current, playing, play, togglePlay } = useContext(PlayerContext);
   const { mediaToken: token } = useAuth();
   const fileUrl = dumpFileUrl(dump, token);

src/components/dump/JournalCard.tsx

@@ -1,3 +1,9 @@
+/**
+ * A dump, as a tile of the journal's mosaic.
+ *
+ * @module
+ */
+
 import { memo } from "react";
 import { Link } from "react-router";
 import { Plural, Trans } from "@lingui/react/macro";
@@ -25,21 +31,34 @@ import {
   usePlayRichContent,
 } from "../../hooks/player/usePlayRichContent.ts";
 
-export type { JournalShape };
-
-interface JournalCardProps {
+/** The props of {@link JournalCard}. */
+export interface JournalCardProps {
+  /** The dump. */
   dump: Dump;
+  /** The tile's footprint in the mosaic. */
   shape: JournalShape;
+  /** Its live vote count. */
   voteCount: number;
+  /** Whether the user upvoted it. */
   voted: boolean;
+  /** Whether the user may vote (signed in). */
   canVote: boolean;
+  /** Upvotes dump `id`; `shownCount` is the count on screen. */
   castVote: (id: string, shownCount?: number) => void;
+  /** Withdraws the vote on dump `id`; `shownCount` is the count on screen. */
   removeVote: (id: string, shownCount?: number) => void;
+  /** Whether the viewer posted it: no unread dot. */
   isOwner?: boolean;
 }
 
-// Memoized, like DumpCard: live events re-render the feed, not every card.
-export const JournalCard = memo(function JournalCard(
+/**
+ * Renders a dump as a mosaic tile — an image card, a pull-quote or a text card,
+ * by its content. A playable card plays; one that can't opens the dump.
+ * Memoized, like DumpCard: live events re-render the feed, not every card.
+ */
+export const JournalCard: React.MemoExoticComponent<
+  (props: JournalCardProps) => React.JSX.Element
+> = memo(function JournalCard(
   { dump, shape, voteCount, voted, canVote, castVote, removeVote, isOwner }:
     JournalCardProps,
 ) {

src/components/dump/RichContentCard.tsx

@@ -1,3 +1,9 @@
+/**
+ * A link's preview card.
+ *
+ * @module
+ */
+
 import { useContext } from "react";
 import { t } from "@lingui/core/macro";
 import type { RichContent } from "../../../shared/dump.ts";
@@ -8,8 +14,11 @@ import {
 } from "../../hooks/player/usePlayRichContent.ts";
 import { Thumbnail } from "../shared/Thumbnail.tsx";
 
-interface RichContentCardProps {
+/** The props of {@link RichContentCard}. */
+export interface RichContentCardProps {
+  /** The link's preview. */
   richContent: RichContent;
+  /** Whether to render the small thumbnail of a card. */
   compact?: boolean;
   /** Overrides richContent.thumbnailUrl with a custom dump thumbnail, if set. */
   thumbnailOverrideUrl?: string;
@@ -17,10 +26,15 @@ interface RichContentCardProps {
   dumpHref?: string;
 }
 
+/**
+ * Renders a link's preview: its thumbnail (or a placeholder), which plays it in
+ * the global player when it can be played and otherwise opens the link, and
+ * full size its site, title and description.
+ */
 export function RichContentCard(
   { richContent, compact = false, thumbnailOverrideUrl, dumpHref }:
     RichContentCardProps,
-) {
+): React.JSX.Element {
   const { current, playing, togglePlay } = useContext(PlayerContext);
   const { playRichContent, pending } = usePlayRichContent();
 

src/components/dump/create/DumpCreateModal.tsx

@@ -1,3 +1,9 @@
+/**
+ * The dump creation modal.
+ *
+ * @module
+ */
+
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Link } from "react-router";
 import { t } from "@lingui/core/macro";
@@ -54,11 +60,13 @@ import { TitleField } from "./TitleField.tsx";
 /** Stable empty result, so rendering doesn't churn on a fresh array each pass. */
 const NO_DUPLICATES: DumpUrlMatch[] = [];
 
+/** The link's preview, as fetched for the form. */
 type UrlPreview =
   | { status: "idle" }
   | { status: "loading" }
   | { status: "done"; reached: boolean; richContent: RichContent | null };
 
+/** The form's fields. */
 interface CreateValues {
   url: string;
   file: File | null;
@@ -68,7 +76,7 @@ interface CreateValues {
 }
 
 /**
- * Whether the pointer is coarse — a touch device, where autofocusing the URL
+ * Checks whether the pointer is coarse — a touch device, where autofocusing the URL
  * input raises a keyboard that covers most of the modal before the user has
  * seen it.
  */
@@ -76,14 +84,27 @@ function prefersNoAutoFocus(): boolean {
   return globalThis.matchMedia?.("(pointer: coarse)").matches ?? false;
 }
 
-interface DumpCreateModalProps {
+/** The props of {@link DumpCreateModal}. */
+export interface DumpCreateModalProps {
+  /** Called to close it. */
   onClose: () => void;
+  /**
+   * A link to start from (the Android share sheet); it replaces any saved
+   * draft.
+   */
   initialUrl?: string;
 }
 
+/**
+ * Renders the modal that posts a dump, in three panels: the link (previewed as
+ * it is typed, with a hint when it was already dumped) or the file, and the
+ * title; the note, categories and visibility; then, once posted, the playlists
+ * to add it to. Everything but the file is kept as a draft until it is posted,
+ * and closing with unsaved work asks first.
+ */
 export function DumpCreateModal(
   { onClose, initialUrl = "" }: DumpCreateModalProps,
-) {
+): React.JSX.Element {
   const { authFetch, authUpload } = useAuth();
   const { injectDump } = useWS();
 

src/components/dump/create/DuplicateNotice.tsx

@@ -1,16 +1,30 @@
+/**
+ * The create form's "already dumped" hint.
+ *
+ * @module
+ */
+
 import { Link } from "react-router";
 import { Plural, Trans } from "@lingui/react/macro";
 import type { DumpUrlMatch } from "../../../../shared/dump.ts";
 import { dumpUrl } from "../../../utils/shared/urls.ts";
 import { relativeTime } from "../../../utils/shared/relativeTime.ts";
 
-/** "Already dumped" hint — never blocking, since reposts are sometimes on purpose. */
+/** The props of {@link DuplicateNotice}. */
+export interface DuplicateNoticeProps {
+  /** The dumps already pointing at the link, most recent first. */
+  matches: DumpUrlMatch[];
+  /** Called when a link to one of them is followed. */
+  onNavigate: () => void;
+}
+
+/**
+ * Renders the "Already dumped" hint — never blocking, since reposts are
+ * sometimes on purpose.
+ */
 export function DuplicateNotice(
-  { matches, onNavigate }: {
-    matches: DumpUrlMatch[];
-    onNavigate: () => void;
-  },
-) {
+  { matches, onNavigate }: DuplicateNoticeProps,
+): React.JSX.Element {
   const [first, ...rest] = matches;
 
   return (

src/components/dump/create/LocalFilePreview.tsx

@@ -1,8 +1,22 @@
+/**
+ * The preview of a picked file, before it is uploaded.
+ *
+ * @module
+ */
+
 import { useEffect, useState } from "react";
 import { MediaPlayer } from "../../player/MediaPlayer.tsx";
 
-/** What a picked file will look like, before it's uploaded. */
-export function LocalFilePreview({ file }: { file: File }) {
+/** The props of {@link LocalFilePreview}. */
+export interface LocalFilePreviewProps {
+  /** The file picked. */
+  file: File;
+}
+
+/** Renders what a picked file will look like, before it's uploaded. */
+export function LocalFilePreview(
+  { file }: LocalFilePreviewProps,
+): React.JSX.Element | null {
   const [src, setSrc] = useState<string | null>(null);
 
   useEffect(() => {

src/components/dump/create/StepIndicator.tsx

@@ -1,21 +1,39 @@
+/**
+ * The create modal's steps, and where the user is in them.
+ *
+ * @module
+ */
+
 import { t } from "@lingui/core/macro";
 
 /**
- * Posting a dump walks three panels. The split is deliberate: categories and
- * visibility used to sit behind a disclosure, where they read as optional and
- * went untouched — they are neither, so "why & where" is a stop on the way to
- * posting rather than something to go looking for.
+ * A panel of the create modal. Posting a dump walks three panels. The split is
+ * deliberate: categories and visibility used to sit behind a disclosure, where
+ * they read as optional and went untouched — they are neither, so "why & where"
+ * is a stop on the way to posting rather than something to go looking for.
  */
 export type Step = "what" | "details" | "playlist";
 
+/** The panels, in order, with their labels. */
 const STEPS: { id: Step; label: () => string }[] = [
   { id: "what", label: () => t`Link or file` },
   { id: "details", label: () => t`Why & where` },
   { id: "playlist", label: () => t`Playlists` },
 ];
 
-/** Where you are in the three panels — and, past the first, how far you got. */
-export function StepIndicator({ current }: { current: Step }) {
+/** The props of {@link StepIndicator}. */
+export interface StepIndicatorProps {
+  /** The panel shown. */
+  current: Step;
+}
+
+/**
+ * Renders where you are in the three panels — and, past the first, how far you
+ * got.
+ */
+export function StepIndicator(
+  { current }: StepIndicatorProps,
+): React.JSX.Element {
   const currentIndex = STEPS.findIndex((s) => s.id === current);
 
   return (

src/components/dump/create/TitleField.tsx

@@ -1,14 +1,34 @@
+/**
+ * The create form's title row.
+ *
+ * @module
+ */
+
 import { useRef } from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
 import { VALIDATION } from "../../../../shared/validation.ts";
 
+/** The props of {@link TitleField}. */
+export interface TitleFieldProps {
+  /** The title field's react-hook-form registration. */
+  registration: UseFormRegisterReturn<"title">;
+  /** Whether the title is being edited. */
+  editing: boolean;
+  /** Starts editing it. */
+  onEdit: () => void;
+  /** Puts the suggestion back; no reset button without it. */
+  onReset?: () => void;
+  /** Whether the row is disabled. */
+  disabled: boolean;
+}
+
 /**
- * Title row shared by both kinds of dump: the suggested title (scraped from the
- * page, or derived from the filename) sits there read-only until the ✎ is used,
- * which is enough to stop stray typing while keeping a correction one click
- * away. Once edited, a reset offers the suggestion back.
+ * Renders the title row shared by both kinds of dump: the suggested title
+ * (scraped from the page, or derived from the filename) sits there read-only
+ * until the ✎ is used, which is enough to stop stray typing while keeping a
+ * correction one click away. Once edited, a reset offers the suggestion back.
  */
 export function TitleField({
   registration,
@@ -16,13 +36,7 @@ export function TitleField({
   onEdit,
   onReset,
   disabled,
-}: {
-  registration: UseFormRegisterReturn<"title">;
-  editing: boolean;
-  onEdit: () => void;
-  onReset?: () => void;
-  disabled: boolean;
-}) {
+}: TitleFieldProps): React.JSX.Element {
   const inputRef = useRef<HTMLInputElement | null>(null);
   const { ref, ...titleReg } = registration;