v3: comments say what the code can't — the documentation pass wanted JSDoc on every export and every field of an exported interface, which filled the code with restatements ("The dump.", "Whether it is loading.", "The props of X.", "Renders the X.") and module docs that told a reader nothing ("The hot and new feeds, and the props every main feed of the index takes."); some were wrong as well as vague. Every comment in api/, shared/ and src/ is rewritten under one rule, now stated in the README's "Comments" section: every module and export still has a JSDoc, and it gives context (who uses it and where), usage (what a caller must know: a precondition, what it leaves to the caller, a side effect) or its place in the chain (where its input comes from, where its output goes); a field, parameter, private function or local gets one only when it adds to its parent's, and context about a whole type goes on the type; a type's doc is phrased from the value's side ("Returned to Y by X when Z", "Passed to Y by X"); full sentences, as short as they can be, no label-colon-list; // goes wherever the code isn't obvious and says why, and the section banners and narration go. Every claim was checked against the code, which turned up some forty comments that were wrong: DumpCard's claimed it was only used by the hot and new feeds, the WebSocket welcome claimed to be a socket's first message (presence comes first), UpdateUserRequest said null removes a description (it keeps it), deletedDumpIds leaves out that it also holds dumps made private, THEME_COLOR claimed to mirror index.html's, and the like. The routers' JSDoc now says where they are mounted and what becomes of a thrown APIException. doc-lint.ts lets a field without a doc through; a module or export without one still fails. No code changes; 204 backend and 628 frontend tests pass, and doc:lint, deno check, deno lint and tsc are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

shared/api.ts

@@ -1,74 +1,77 @@
 /**
- * The envelope every endpoint answers with, the error codes it carries, the
- * shape of a paginated list, and {@link Wire}, which maps a type to what JSON
- * makes of it.
+ * Defines the envelope every JSON endpoint answers with, and {@link Wire}, the
+ * form a type takes once it has crossed JSON. The routes build the envelope,
+ * and the frontend's API helpers unwrap it.
  *
  * @module
  */
 
-/** The error codes an {@link APIError} carries, by name. */
+/**
+ * The codes an {@link APIError} may carry. The frontend shows the message and
+ * doesn't read the code, and a code goes with several statuses.
+ */
 export const APIErrorCode = {
-  /** The request is malformed or not allowed in the current state. */
   BAD_REQUEST: "BAD_REQUEST",
-  /** What the request names doesn't exist, or the caller may not see it. */
+  /** Also answers for what exists but the caller may not see. */
   NOT_FOUND: "NOT_FOUND",
-  /** The server failed. */
+  /** Sent by the error middleware for any error that isn't an APIException. */
   SERVER_ERROR: "SERVER_ERROR",
-  /** A remote site took too long to answer. */
+  /** Nothing sends it. */
   TIMEOUT: "TIMEOUT",
-  /** The caller isn't signed in, or may not do this. */
+  /**
+   * Sent with 401 to a caller not signed in, and with 403 to one who may not.
+   */
   UNAUTHORIZED: "UNAUTHORIZED",
-  /** The request body failed validation. */
   VALIDATION_ERROR: "VALIDATION_ERROR",
 } as const;
 
-/** One of the {@link APIErrorCode} values. */
+/** Carried by the backend's `APIException`, and sent in an {@link APIError}. */
 export type APIErrorCode = typeof APIErrorCode[keyof typeof APIErrorCode];
 
-/** What went wrong, in a failed response. */
+/**
+ * Sent in an {@link APIFailure}. The frontend shows `message` to the user, so
+ * it is written for them.
+ */
 export interface APIError {
-  /** The kind of failure. */
   code: APIErrorCode;
-  /** A human-readable explanation. */
   message: string;
 }
 
-/** A successful response, carrying its payload. */
+/** Sent by a route that succeeded, around its payload. */
 export interface APISuccess<T> {
-  /** Always true. */
   success: true;
-  /** The payload. */
   data: T;
-  /** Never set on success. */
   error?: never;
 }
 
-/** A failed response, carrying its error. */
+/**
+ * Sent by the error middleware when a request fails, and by the few routes
+ * that answer an error themselves.
+ */
 export interface APIFailure {
-  /** Always false. */
   success: false;
-  /** Never set on failure. */
   data?: never;
-  /** What went wrong. */
   error: APIError;
 }
 
-/** What every endpoint answers with, narrowed by `success`. */
+/**
+ * Returned by every JSON endpoint. A reader tells the two apart by `success`.
+ */
 export type APIResponse<T> = APISuccess<T> | APIFailure;
 
-/** One page of a list. */
+/**
+ * Returned by the list endpoints, as the `data` of an {@link APISuccess}.
+ */
 export interface PaginatedData<T> {
-  /** The page's items. */
   items: T[];
-  /** Whether another page follows. */
   hasMore: boolean;
-  /** The whole list's size — only where it's shown (search results). */
+  /** The size of the whole list, set only by search, which shows it. */
   total?: number;
 }
 
 /**
- * `T` as it arrives over JSON (HTTP, the socket, localStorage): every Date is
- * an ISO string.
+ * `T` as the client reads it from JSON, over HTTP, the socket or
+ * localStorage, where every `Date` has become an ISO string.
  */
 export type Wire<T> = T extends Date ? string
   : T extends readonly (infer U)[] ? Wire<U>[]