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/utils/chat/draft.ts

@@ -1,16 +1,30 @@
+/**
+ * The chat's unsent message, kept per user in sessionStorage. The draft and
+ * reply target outlive the chat — closing it, or reloading the tab, keeps a
+ * half-written message.
+ *
+ * @module
+ */
+
 import type { ChatReplyTarget } from "../../contexts/ws/WSContext.ts";
 
-// The draft and reply target outlive the chat — closing it, or reloading the
-// tab, keeps a half-written message.
+/** An unsent chat message. */
 export interface StoredDraft {
+  /** The message as typed so far. */
   draft: string;
+  /** The message it replies to, if any. */
   replyTarget: ChatReplyTarget | null;
 }
 
+/** Returns the sessionStorage key of the draft of `userId`. */
 function draftKey(userId: string): string {
   return `chat-draft:${userId}`;
 }
 
+/**
+ * Returns the stored draft of `userId`, empty when there is none or no one is
+ * signed in.
+ */
 export function readDraft(userId: string | undefined): StoredDraft {
   if (userId) {
     try {
@@ -26,6 +40,7 @@ export function readDraft(userId: string | undefined): StoredDraft {
   return { draft: "", replyTarget: null };
 }
 
+/** Stores `value` as the draft of `userId`, or removes it when it is empty. */
 export function writeDraft(
   userId: string | undefined,
   value: StoredDraft,

src/utils/chat/message.ts

@@ -1,25 +1,41 @@
+/**
+ * Rules for a chat message: when it can be sent, how it is shown, and its
+ * one-line preview.
+ *
+ * @module
+ */
+
 import { t } from "@lingui/core/macro";
 import { markdownToPlainText } from "./text.ts";
 import { isEmojiOnly } from "../editor/text.ts";
 import { VALIDATION } from "../../../shared/validation.ts";
 
-// The counter only shows once a message is getting near the limit.
+/**
+ * The length from which the character counter shows — only once a message is
+ * getting near the limit.
+ */
 export const COUNT_FROM = 1800;
 
-// What the server holds a message to: its length once trimmed.
+/**
+ * Checks whether `draft` can be sent, by what the server holds a message to:
+ * its length once trimmed.
+ */
 export function sendable(draft: string): boolean {
   const body = draft.trim();
   return body.length > 0 && body.length <= VALIDATION.CHAT_MESSAGE_MAX;
 }
 
-// A message of nothing but a few emoji is shown large, as chats do.
+/**
+ * Returns the class of a message's text: a message of nothing but a few emoji
+ * is shown large, as chats do.
+ */
 export function messageTextClass(body: string): string {
   return isEmojiOnly(body)
     ? "chat-message-text chat-message-text--jumbo"
     : "chat-message-text";
 }
 
-// One line of plain text, for reply previews.
+/** Returns `body` as one line of plain text, for reply previews. */
 export function snippet(body: string): string {
   return markdownToPlainText(body, t`image`);
 }

src/utils/chat/text.ts

@@ -1,9 +1,15 @@
+/**
+ * Text helpers for the live chat.
+ *
+ * @module
+ */
+
 import { MENTION_RE } from "../../../shared/mention.ts";
 
-// Text helpers for the live chat.
-
-/** Whether `body` @-mentions `username` (case-insensitively), by the same rule
- * the server uses to send mention notifications. */
+/**
+ * Checks whether `body` @-mentions `username` (case-insensitively), by the same
+ * rule the server uses to send mention notifications.
+ */
 export function mentionsUser(body: string, username: string): boolean {
   const target = username.toLowerCase();
   for (const m of body.matchAll(MENTION_RE)) {
@@ -13,10 +19,10 @@ export function mentionsUser(body: string, username: string): boolean {
 }
 
 /**
- * Flattens chat markdown to one line of plain text, for the reply previews:
- * images become a label, links their text, and markup characters go. Also
- * copes with a body the server cut short mid-link, which would otherwise show
- * a dangling half-URL.
+ * Returns the chat markdown `md` flattened to one line of plain text, for the
+ * reply previews: images become their alt text or `imageLabel`, links their
+ * text, and markup characters go. Also copes with a body the server cut short
+ * mid-link, which would otherwise show a dangling half-URL.
  */
 export function markdownToPlainText(md: string, imageLabel: string): string {
   return md

src/utils/chat/time.ts

@@ -1,16 +1,23 @@
-// Timestamps in the chat: day separators and the grouped-message gutter.
+/**
+ * Timestamps in the chat: day separators and the grouped-message gutter.
+ *
+ * @module
+ */
 
 import { t } from "@lingui/core/macro";
-import { i18n } from "../../i18n.ts";
+import { i18n } from "@lingui/core";
 
+/** Checks whether `a` and `b` fall on the same local day. */
 export function isSameDay(a: Date, b: Date): boolean {
   return a.getFullYear() === b.getFullYear() &&
     a.getMonth() === b.getMonth() &&
     a.getDate() === b.getDate();
 }
 
-// Human label for a day separator: "Today"/"Yesterday" for the two most recent
-// days, otherwise a localized full date.
+/**
+ * Returns the label of the day separator for `date`: "Today" or "Yesterday" for
+ * the two most recent days, otherwise a localized full date.
+ */
 export function dayLabel(date: Date): string {
   const now = new Date();
   if (isSameDay(date, now)) return t`Today`;
@@ -25,8 +32,11 @@ export function dayLabel(date: Date): string {
   });
 }
 
-// Hours and minutes only, for the narrow gutter beside a grouped message — the
-// day period ("PM") is dropped to fit; its tooltip has the full timestamp.
+/**
+ * Returns the hours and minutes of `date`, for the narrow gutter beside a
+ * grouped message — the day period ("PM") is dropped to fit; its tooltip has
+ * the full timestamp.
+ */
 export function clockTime(date: Date): string {
   return new Intl.DateTimeFormat(i18n.locale, {
     hour: "numeric",