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/editor/useEmojiTrigger.ts

@@ -1,35 +1,76 @@
+/**
+ * The editor's emoji picker state: opened by typing `:query` or from the
+ * button.
+ *
+ * @module
+ */
+
 import { useCallback, useRef, useState } from "react";
 import { insideCode } from "../../utils/editor/text.ts";
 
-// Trigger: ':' not preceded by a letter, digit or another ':', followed by a
-// letter then at least one more word char / '+' / '-'. Two characters, not
-// one, so emoticons like ':D' or ':P' — and "note:" or "12:30" — don't open
-// the picker; Unicode letters so French names ("coeur", "cœur") search too.
+/**
+ * Trigger: ':' not preceded by a letter, digit or another ':', followed by a
+ * letter then at least one more word char / '+' / '-'. Two characters, not one,
+ * so emoticons like ':D' or ':P' — and "note:" or "12:30" — don't open the
+ * picker; Unicode letters so French names ("coeur", "cœur") search too.
+ */
 const TRIGGER_RE = /(?<![\p{L}\p{N}_:]):(\p{L}[\p{L}\p{N}_+-]+)$/u;
 
 /**
+ * The picker's mode.
+ *
  * `inline`: opened by typing `:query` — focus stays in the textarea, the
  * picker's search follows what's typed, and a pick replaces the `:query`.
- * `browse`: opened from the button — focus goes to the picker's own search,
- * and a pick lands at the caret.
+ * `browse`: opened from the button — focus goes to the picker's own search, and
+ * a pick lands at the caret.
  */
 export type EmojiMode = "closed" | "inline" | "browse";
 
+/** The picker's state. */
 interface EmojiState {
+  /** Its mode. */
   mode: EmojiMode;
+  /** What it searches for. */
   query: string;
-  /** The range of the textarea's value a pick replaces. */
+  /** The range of the textarea's value a pick replaces: its start… */
   start: number;
+  /** …and its end. */
   end: number;
 }
 
+/** The closed picker. */
 const CLOSED: EmojiState = { mode: "closed", query: "", start: 0, end: 0 };
 
+/** What {@link useEmojiTrigger} returns. */
+export interface UseEmojiTriggerResult {
+  /** The picker's mode. */
+  emojiMode: EmojiMode;
+  /** What the picker searches for. */
+  emojiQuery: string;
+  /**
+   * Call on every change (with `open`) and caret move (without): follows an
+   * inline `:query` as it's typed, and closes once the caret leaves it. Leaves
+   * a browse-mode picker alone.
+   */
+  syncEmojiTrigger: (value: string, cursor: number, open: boolean) => void;
+  /** Opens the picker from the button, a pick replacing `[start, end)`. */
+  openEmojiBrowser: (start: number, end: number) => void;
+  /** Sets what the picker searches for. */
+  setEmojiQuery: (query: string) => void;
+  /** Inserts the emoji `native` and closes the picker. */
+  selectEmoji: (native: string) => void;
+  /** Closes the picker. */
+  closeEmoji: () => void;
+}
+
+/**
+ * Returns the emoji picker's state for a textarea; a pick goes through
+ * `replace`, which replaces `[start, end)` of the textarea's value, with a
+ * space after when `word` is set (see TextEditor).
+ */
 export function useEmojiTrigger(
-  /** Replaces `[start, end)` of the textarea's value, with a space after
-   * when `word` is set; see TextEditor. */
   replace: (start: number, end: number, text: string, word: boolean) => void,
-) {
+): UseEmojiTriggerResult {
   const [state, setStateRaw] = useState<EmojiState>(CLOSED);
   // Mirrored synchronously, so a change and a caret move in the same event
   // each see what the other just decided.
@@ -39,11 +80,6 @@ export function useEmojiTrigger(
     setStateRaw(next);
   }, []);
 
-  /**
-   * Call on every change (with `open`) and caret move (without): follows an
-   * inline `:query` as it's typed, and closes once the caret leaves it.
-   * Leaves a browse-mode picker alone.
-   */
   const syncEmojiTrigger = useCallback(
     (value: string, cursor: number, open: boolean) => {
       const s = stateRef.current;

src/hooks/editor/useMentionAutocomplete.ts

@@ -1,3 +1,10 @@
+/**
+ * The editor's @mention autocomplete: the `@query` under the caret, the users
+ * it matches, and keyboard selection.
+ *
+ * @module
+ */
+
 import {
   type KeyboardEvent,
   useCallback,
@@ -7,24 +14,28 @@ import {
 } from "react";
 import { API_URL } from "../../config/api.ts";
 import { insideCode } from "../../utils/editor/text.ts";
+import type { UserSuggestion } from "../../../shared/user.ts";
 
-export interface UserResult {
-  id: string;
-  username: string;
-  avatarMime: string | null;
-}
-
+/** The autocomplete's state. */
 interface MentionState {
+  /** Whether the list is shown. */
   open: boolean;
+  /** The name typed after the `@`. */
   query: string;
-  /** Where the `@` sits, and the caret after the query: the range a pick
-   * replaces. */
+  /**
+   * Where the `@` sits, and the caret after the query: the range a pick
+   * replaces.
+   */
   start: number;
+  /** The caret after the query. */
   end: number;
-  results: UserResult[];
+  /** The matching users. */
+  results: UserSuggestion[];
+  /** The highlighted match. */
   selectedIndex: number;
 }
 
+/** The closed autocomplete. */
 const CLOSED: MentionState = {
   open: false,
   query: "",
@@ -34,11 +45,17 @@ const CLOSED: MentionState = {
   selectedIndex: 0,
 };
 
-// The server's mention rule (api/services/notification-service.ts): an `@` not
-// preceded by `[`, `(` or a word character, so what's offered is exactly what
-// would notify.
+/**
+ * The server's mention rule (api/services/notification-service.ts): an `@` not
+ * preceded by `[`, `(` or a word character, so what's offered is exactly what
+ * would notify.
+ */
 const TRIGGER_RE = /(?<![[(\w])@(\w+)$/;
 
+/**
+ * Returns the `@query` that ends at `pos` in `value`, or null when there is
+ * none (or it is inside code).
+ */
 function getMentionQuery(
   value: string,
   pos: number,
@@ -62,11 +79,39 @@ export type MentionKey = Pick<
   | "stopPropagation"
 >;
 
+/** What {@link useMentionAutocomplete} returns. */
+export interface UseMentionAutocompleteResult {
+  /** Whether the list is shown. */
+  mentionOpen: boolean;
+  /** The matching users. */
+  mentionResults: UserSuggestion[];
+  /** The highlighted match. */
+  mentionSelectedIndex: number;
+  /**
+   * Call on every change (with `lookup`) and caret move (without): tracks the
+   * `@query` under the caret, searching for it after a short pause, and closes
+   * once the caret leaves it.
+   */
+  syncMention: (value: string, pos: number, lookup: boolean) => void;
+  /** Closes the list. */
+  closeMention: () => void;
+  /**
+   * Handles arrows, Enter/Tab and Escape while the list is shown; returns
+   * whether it handled the key.
+   */
+  handleMentionKeyDown: (e: MentionKey) => boolean;
+  /** Inserts `@username` and closes the list. */
+  handleMentionSelect: (username: string) => void;
+}
+
+/**
+ * Returns the @mention autocomplete for a textarea; a pick goes through
+ * `replace`, which replaces `[start, end)` of the textarea's value, with a
+ * space after when `word` is set (see TextEditor).
+ */
 export function useMentionAutocomplete(
-  /** Replaces `[start, end)` of the textarea's value, with a space after
-   * when `word` is set; see TextEditor. */
   replace: (start: number, end: number, text: string, word: boolean) => void,
-) {
+): UseMentionAutocompleteResult {
   const [state, setStateRaw] = useState<MentionState>(CLOSED);
   // Mirrored synchronously so the key handler and a fetch landing late both
   // read what the last keystroke decided, not the last render.
@@ -90,11 +135,6 @@ export function useMentionAutocomplete(
     if (stateRef.current !== CLOSED) setState(CLOSED);
   }, [cancelLookup, setState]);
 
-  /**
-   * Call on every change (with `lookup`) and caret move (without): tracks the
-   * `@query` under the caret, searching for it after a short pause, and closes
-   * once the caret leaves it.
-   */
   const syncMention = useCallback(
     (value: string, pos: number, lookup: boolean) => {
       const mention = getMentionQuery(value, pos);
@@ -161,7 +201,6 @@ export function useMentionAutocomplete(
     [close, replace],
   );
 
-  /** Returns whether it handled the key. */
   const handleMentionKeyDown = useCallback(
     (e: MentionKey): boolean => {
       const s = stateRef.current;