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/hooks/feed/useFading.ts

@@ -1,18 +1,35 @@
+/**
+ * The dismissal animation of items leaving a list: a grace period, then a
+ * collapse.
+ *
+ * @module
+ */
+
 import { useCallback, useEffect, useRef, useState } from "react";
 
 /**
- * Manages a 2-second cooldown + 350ms dismissal animation for a set of items.
- *
- * Call `startFading(id)` when an item should begin fading out.
- * Call `cancelFading(id)` to abort the animation (e.g. the action was reversed).
- * Use the returned `fading` record to apply CSS classes:
- *   - `"cooldown"`  → item is in the 2-second grace period (darkened)
- *   - `"dismissing"` → item is collapsing (opacity 0 + grid-row collapse)
+ * Where an item is in its dismissal: `cooldown` is the 2-second grace period
+ * (darkened), `dismissing` the collapse (opacity 0 + grid-row collapse).
  */
-export function useFading() {
-  const [fading, setFading] = useState<
-    Record<string, "cooldown" | "dismissing">
-  >({});
+export type FadeState = "cooldown" | "dismissing";
+
+/** What {@link useFading} returns. */
+export interface UseFadingResult {
+  /** The items being dismissed, by id, and where each is; for CSS classes. */
+  fading: Record<string, FadeState>;
+  /** Starts dismissing item `id`. */
+  startFading: (id: string) => void;
+  /** Stops dismissing item `id` (e.g. the action was reversed). */
+  cancelFading: (id: string) => void;
+  /** Cancels all in-progress animations (e.g. on page navigation). */
+  cancelAll: () => void;
+}
+
+/**
+ * Returns a 2-second cooldown + 350ms dismissal animation for a set of items.
+ */
+export function useFading(): UseFadingResult {
+  const [fading, setFading] = useState<Record<string, FadeState>>({});
   const cancels = useRef<Map<string, () => void>>(new Map());
 
   useEffect(() => () => {
@@ -69,7 +86,6 @@ export function useFading() {
     cancels.current.get(id)?.();
   }, []);
 
-  /** Cancel all in-progress animations (e.g. on page navigation). */
   const cancelAll = useCallback(() => {
     cancels.current.forEach((c) => c());
   }, []);