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/player/MediaPlayer.tsx

@@ -1,3 +1,9 @@
+/**
+ * The site's audio and video player.
+ *
+ * @module
+ */
+
 import { useEffect, useRef, useState } from "react";
 import { fmt } from "../../utils/player/duration.ts";
 import { t } from "@lingui/core/macro";
@@ -11,16 +17,26 @@ import { SeekBar } from "./SeekBar.tsx";
 import { Waveform } from "./Waveform.tsx";
 import { rememberVolume, storedVolume } from "../../utils/player/volume.ts";
 
+/** How long a playing video's controls stay after the pointer stops, in ms. */
 const HIDE_DELAY = 2500;
 
-interface MediaPlayerProps {
+/** The props of {@link MediaPlayer}. */
+export interface MediaPlayerProps {
+  /** The media's URL. */
   src: string;
+  /** Whether it is audio or video. */
   kind: "audio" | "video";
+  /** The media's type. */
   mime?: string;
+  /** A video's still before it plays. */
   poster?: string;
+  /** Whether it starts playing on mount. */
   autoplay?: boolean;
+  /** Where it starts, in seconds. */
   startTime?: number;
+  /** Called when it starts or stops playing. */
   onPlayStateChange?: (playing: boolean) => void;
+  /** Called as it plays, with the playhead and the duration. */
   onTimeUpdate?: (time: number, duration: number) => void;
   /** Fired when the media reaches its end — the queue's advance hook. */
   onEnded?: () => void;
@@ -30,10 +46,17 @@ interface MediaPlayerProps {
   /** "waveform" (default) decodes peaks from the source; "progress" draws a
    *  slim seek bar and never fetches the media a second time. */
   trackStyle?: "waveform" | "progress";
+  /** Receives its seek handle, for the global player's controls. */
   seekRef?: { current: ((t: number) => void) | null };
+  /** Receives its play/pause handle, for the global player's controls. */
   toggleRef?: { current: (() => void) | null };
 }
 
+/**
+ * Renders a media element with the site's own controls: play/pause, a waveform
+ * or seek bar, time, volume (remembered across players) and, for video,
+ * fullscreen.
+ */
 export function MediaPlayer(
   {
     src,
@@ -50,7 +73,7 @@ export function MediaPlayer(
     seekRef,
     toggleRef,
   }: MediaPlayerProps,
-) {
+): React.JSX.Element {
   const mediaRef = useRef<HTMLMediaElement>(null);
   const [playing, setPlaying] = useState(false);
   const [current, setCurrent] = useState(0);