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/editor/Markdown.tsx

@@ -1,18 +1,33 @@
+/**
+ * Markdown, rendered: GFM, @mentions as profile links, line breaks kept, and
+ * links into the app kept in the app.
+ *
+ * @module
+ */
+
 import { memo } from "react";
 import { Link } from "react-router";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 
-interface MarkdownProps {
+/** The props of {@link Markdown}. */
+export interface MarkdownProps {
+  /** The Markdown source. */
   children: string;
+  /** An extra class. */
   className?: string;
+  /** Whether it is a line-clamped teaser inside a card: images are dropped. */
   inline?: boolean;
 }
 
-// The mention rule the server notifies by (see utils/chatText.ts): an `@` not
-// preceded by a word character, so an email address isn't a mention.
+/**
+ * The mention rule the server notifies by (see shared/mention.ts), on parsed
+ * text: an `@` not preceded by a word character, so an email address isn't a
+ * mention. Link syntax is already parsed away here.
+ */
 const MENTION_RE = /(?<!\w)@(\w+)/g;
 
+/** A node of the Markdown syntax tree, the part the plugins read. */
 interface MdNode {
   type: string;
   value?: string;
@@ -59,7 +74,7 @@ function remarkMentions() {
 }
 
 /**
- * A single newline is a line break, as it is in chat everywhere: markdown's
+ * Turns a single newline into a line break, as in chat everywhere: markdown's
  * own rule folds it into a space, so a message typed on three lines with
  * Shift+Enter came out as one. (Code keeps its newlines; it has no text
  * nodes.)
@@ -82,10 +97,13 @@ function remarkBreaks() {
   return (tree: MdNode) => walk(tree);
 }
 
+/** The remark plugins, in order. */
 const REMARK_PLUGINS = [remarkGfm, remarkMentions, remarkBreaks];
 
-/** The path of a link into this app — relative, or absolute to this origin —
- * or null for anywhere else. */
+/**
+ * Returns the path of a link into this app — relative, or absolute to this
+ * origin — or null for anywhere else (the API's files included).
+ */
 function internalPath(href: string | undefined): string | null {
   if (!href) return null;
   if (href.startsWith("/") && !href.startsWith("//")) {
@@ -102,9 +120,14 @@ function internalPath(href: string | undefined): string | null {
   }
 }
 
+/** react-markdown's element overrides. */
 type Components = React.ComponentProps<typeof ReactMarkdown>["components"];
 
-// Static components objects — defined once at module scope to avoid recreation on every render
+/**
+ * The element overrides, defined once at module scope to avoid recreation on
+ * every render. Mentions and links to other pages here stay in the app; the
+ * rest open in a new tab; a wide GFM table scrolls inside its own box.
+ */
 const MARKDOWN_COMPONENTS: Components = {
   // Mentions and links to other pages here stay in the app; the rest open
   // in a new tab.
@@ -128,17 +151,24 @@ const MARKDOWN_COMPONENTS: Components = {
   ),
 };
 
-// Inline renderings are line-clamped teasers inside cards, where an embedded
-// image blows the layout apart. Drop images there — the full description is
-// one click away on the detail page.
+/**
+ * The element overrides of an inline rendering. Inline renderings are
+ * line-clamped teasers inside cards, where an embedded image blows the layout
+ * apart; images are dropped there — the full description is one click away on
+ * the detail page.
+ */
 const INLINE_MARKDOWN_COMPONENTS: Components = {
   ...MARKDOWN_COMPONENTS,
   img: () => null,
 };
 
-// Memoized: parsing runs the whole remark pipeline, and the text rarely
-// changes when the component around it re-renders.
-export const Markdown = memo(function Markdown(
+/**
+ * Renders Markdown. Memoized: parsing runs the whole remark pipeline, and the
+ * text rarely changes when the component around it re-renders.
+ */
+export const Markdown: React.MemoExoticComponent<
+  (props: MarkdownProps) => React.JSX.Element
+> = memo(function Markdown(
   { children, className, inline = false }: MarkdownProps,
 ) {
   return (