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/comment/CommentForm.tsx

@@ -1,4 +1,9 @@
-import React from "react";
+/**
+ * The comment editor, for posting, replying and editing.
+ *
+ * @module
+ */
+
 import { Controller, FormProvider } from "react-hook-form";
 import { Trans } from "@lingui/react/macro";
 import { VALIDATION } from "../../../shared/validation.ts";
@@ -7,26 +12,36 @@ import { FormError } from "../form/FormError.tsx";
 import { SubmitButton } from "../form/SubmitButton.tsx";
 import { useApiForm } from "../../hooks/form/useApiForm.ts";
 
+/** The props of {@link CommentForm}. */
 export interface CommentFormProps {
   /** Async submit; throw to surface a root error, resolve to clear/close. */
   onSubmit: (body: string) => Promise<void>;
+  /** The submit button's label. */
   submitLabel: React.ReactNode;
+  /** The submit button's label while submitting. */
   pendingLabel: React.ReactNode;
+  /** The title of the error shown when the submit fails. */
   errorTitle: string;
+  /** The editor's placeholder. */
   placeholder?: string;
+  /** The initial text; empty by default. */
   defaultValue?: string;
+  /** Called by the Cancel button; no Cancel button without it. */
   onCancel?: () => void;
   /** Top-level form: only show Cancel once there's text to discard. */
   cancelWhenEmpty?: boolean;
+  /** Forwarded to the editor so callers can focus it. */
   editorRef?: React.Ref<TextEditorHandle>;
   /** `top` renders the avatar-flanked layout; `inline` is for reply/edit. */
   layout?: "inline" | "top";
+  /** Shown before the editor in the `top` layout (the user's avatar). */
   leading?: React.ReactNode;
+  /** An extra class for the form. */
   className?: string;
 }
 
 /**
- * Single-field comment editor (post / reply / edit). Wraps the shared
+ * Renders a single-field comment editor (post / reply / edit). Wraps the shared
  * react-hook-form lifecycle so the three call sites stay identical.
  */
 export function CommentForm({
@@ -42,7 +57,7 @@ export function CommentForm({
   layout = "inline",
   leading,
   className,
-}: CommentFormProps) {
+}: CommentFormProps): React.JSX.Element {
   const form = useApiForm<{ body: string }>({
     defaultValues: { body: defaultValue },
   });

src/components/comment/CommentNode.tsx

@@ -1,4 +1,10 @@
-import React, { useRef, useState } from "react";
+/**
+ * A comment in the thread, with its replies.
+ *
+ * @module
+ */
+
+import { useRef, useState } from "react";
 import { Link } from "react-router";
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
@@ -25,18 +31,32 @@ import { useAuth } from "../../hooks/auth/useAuth.ts";
 import { expectOk } from "../../utils/shared/api.ts";
 import { CommentForm } from "./CommentForm.tsx";
 
-interface CommentNodeProps {
+/** The props of {@link CommentNode}. */
+export interface CommentNodeProps {
+  /** The comment. */
   comment: Comment;
+  /** Every comment's replies, by parent id. */
   tree: Map<string, Comment[]>;
+  /** How deep it is nested. */
   depth: number;
+  /** The id of the dump it is under. */
   dumpId: string;
+  /** The signed-in user, null when signed out. */
   currentUser: SelfUser | null;
+  /** The session token. */
   token: string | null;
+  /** Called with a reply posted. */
   onCommentCreated: (comment: Comment) => void;
+  /** Called with the id of a comment deleted. */
   onCommentDeleted: (commentId: string) => void;
+  /** Called with a comment edited. */
   onCommentUpdated: (comment: Comment) => void;
 }
 
+/**
+ * Renders a comment — its author, time, text and like button, with reply, edit
+ * and delete for whoever may — and under it its replies, recursively.
+ */
 export function CommentNode({
   comment,
   tree,
@@ -47,7 +67,7 @@ export function CommentNode({
   onCommentCreated,
   onCommentDeleted,
   onCommentUpdated,
-}: CommentNodeProps) {
+}: CommentNodeProps): React.JSX.Element {
   const [replyOpen, setReplyOpen] = useState(false);
   const [editOpen, setEditOpen] = useState(false);
   const [confirmDelete, setConfirmDelete] = useState(false);

src/components/comment/CommentThread.tsx

@@ -1,3 +1,9 @@
+/**
+ * A dump's comment thread.
+ *
+ * @module
+ */
+
 import { useMemo } from "react";
 import { t } from "@lingui/core/macro";
 import { Plural, Trans } from "@lingui/react/macro";
@@ -12,16 +18,28 @@ import { expectOk } from "../../utils/shared/api.ts";
 import { CommentForm } from "./CommentForm.tsx";
 import { CommentNode } from "./CommentNode.tsx";
 
-interface CommentThreadProps {
+/** The props of {@link CommentThread}. */
+export interface CommentThreadProps {
+  /** The dump's id. */
   dumpId: string;
+  /** Every comment on the dump. */
   comments: Comment[];
+  /** The signed-in user, null when signed out. */
   currentUser: SelfUser | null;
+  /** The session token. */
   token: string | null;
+  /** Called with a comment posted. */
   onCommentCreated: (comment: Comment) => void;
+  /** Called with the id of a comment deleted. */
   onCommentDeleted: (commentId: string) => void;
+  /** Called with a comment edited. */
   onCommentUpdated: (comment: Comment) => void;
 }
 
+/**
+ * Returns the replies of each comment of `comments`, by parent id (`root` for
+ * the top level).
+ */
 function buildTree(comments: Comment[]): Map<string, Comment[]> {
   const map = new Map<string, Comment[]>();
   for (const c of comments) {
@@ -32,6 +50,10 @@ function buildTree(comments: Comment[]): Map<string, Comment[]> {
   return map;
 }
 
+/**
+ * Renders the form that posts a comment (for a signed-in user), and the thread
+ * under it.
+ */
 export function CommentThread({
   dumpId,
   comments,
@@ -40,7 +62,7 @@ export function CommentThread({
   onCommentCreated,
   onCommentDeleted,
   onCommentUpdated,
-}: CommentThreadProps) {
+}: CommentThreadProps): React.JSX.Element {
   const tree = useMemo(() => buildTree(comments), [comments]);
   const roots = tree.get("root") ?? [];
   const { authFetch } = useAuth();