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>

api/remote/bandcamp-tralbum.ts

@@ -1,18 +1,8 @@
 /**
- * Parser for Bandcamp's `data-tralbum` attribute.
- *
- * Every Bandcamp track and album page carries the whole release — titles,
- * durations and signed mp3 stream URLs — as one HTML-escaped JSON blob on a
- * `data-tralbum` attribute. One fetch of an album page therefore yields every
- * track's stream URL; there is no per-track request.
- *
- * The stream URLs are signed and expire 24h after the page was fetched, which
- * is why nothing here is ever persisted to `rich_content` — see
- * `api/routes/bandcamp.ts` for the resolve-at-play-time endpoint.
- *
- * The shape is undocumented, so every field is treated as optional and the
- * whole parse is best-effort: a `null` return means "not a Bandcamp page",
- * which callers turn into a fallback to the iframe embed.
+ * Reads a release out of a Bandcamp page, for `bandcamp-streams.ts`. Every
+ * track and album page carries the whole release, stream URLs included, as
+ * HTML-escaped JSON in a `data-tralbum` attribute, so one fetch covers an
+ * album. The format is undocumented, so every field is treated as optional.
  *
  * @module
  */
@@ -20,19 +10,16 @@
 import type { Tralbum, TralbumTrack } from "../../shared/player.ts";
 
 /**
- * The hostnames Bandcamp serves its own sites from, anchored at the end so that `bandcamp.com.example.org` cannot pass. Artists on custom
- * domains do not match this and keep using the embed.
+ * Matches the hostnames `bandcamp-streams.ts` accepts: bandcamp.com and its
+ * subdomains, and not `bandcamp.com.example.org`. An artist on a custom domain
+ * doesn't match, and the player falls back to the embed.
  */
 export const BANDCAMP_HOST_RE = /(?:^|\.)bandcamp\.com$/;
 
 /**
- * Decodes HTML entities in a single pass.
- *
- * The single pass is the point: `decodeHtmlEntities` in remote/html.ts
- * replaces `&` before `"`, so an escaped-ampersand-then-quot sequence
- * (`"`, i.e. the literal text `"` inside a title) decodes twice
- * and yields a bare `"` — which lands inside the JSON string and breaks the
- * parse. Matching every entity form in one regex means each is replaced once.
+ * Decodes HTML entities in a single pass. `html.ts` decodes `&` before
+ * `"`, which turns a title's literal `"` (escaped as `"`)
+ * into a bare `"` that breaks the JSON.
  */
 function decodeEntitiesOnce(input: string): string {
   const named: Record<string, string> = {
@@ -53,7 +40,7 @@ function decodeEntitiesOnce(input: string): string {
   );
 }
 
-/** Returns the URL of the large square artwork numbered `artId`. */
+/** Returns the URL of the artwork `artId`; undefined when it isn't numeric. */
 function artworkUrl(artId: unknown): string | undefined {
   if (typeof artId !== "number" && typeof artId !== "string") return undefined;
   const id = String(artId).trim();
@@ -63,8 +50,9 @@ function artworkUrl(artId: unknown): string | undefined {
 }
 
 /**
- * Pulls the `data-tralbum` blob out of a Bandcamp page and normalises it.
- * Returns null when the page has no blob, no audio, or nothing parseable.
+ * Returns the release on the Bandcamp page `html`, fetched from `sourceUrl`;
+ * null when the page has no release data, no audio or no streamable track.
+ * Stream URLs outside bcbits.com are dropped.
  */
 export function parseTralbum(html: string, sourceUrl: string): Tralbum | null {
   const match = html.match(/\bdata-tralbum=(["'])([\s\S]*?)\1/);
@@ -84,8 +72,8 @@ export function parseTralbum(html: string, sourceUrl: string): Tralbum | null {
     const t = (entry ?? {}) as Record<string, unknown>;
     const file = (t.file ?? {}) as Record<string, unknown>;
     const mp3 = typeof file["mp3-128"] === "string" ? file["mp3-128"] : null;
-    // Only ever hand out bcbits URLs. Without this the endpoint would relay
-    // whatever host a hostile page put in the blob straight to the browser.
+    // A hostile page could put any host here, and the endpoint would hand it
+    // to the browser.
     const streamUrl = mp3 && isBcbitsUrl(mp3) ? mp3 : null;
     return {
       index,
@@ -117,7 +105,6 @@ export function parseTralbum(html: string, sourceUrl: string): Tralbum | null {
   };
 }
 
-/** Checks whether `url` is an https URL on Bandcamp's bcbits.com CDN. */
 function isBcbitsUrl(url: string): boolean {
   try {
     const { protocol, hostname } = new URL(url);