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/services/playlist-service.ts

@@ -1,7 +1,8 @@
 /**
- * Playlists: managing them and their dumps, and reading them as each viewer
- * may see them. A playlist is public or private to its owner; its members are
- * filtered per viewer (see {@link isMemberVisibleTo}).
+ * Stores playlists and the ordered dumps in them. The playlist routes call it,
+ * and so do the search, users and dumps routes to list playlists. Every write
+ * is broadcast over the WebSocket, and a viewer is only ever sent the dumps
+ * {@link isMemberVisibleTo} lets them see.
  *
  * @module
  */
@@ -42,16 +43,18 @@ import {
 } from "../lib/playlist-members.ts";
 
 /**
- * The columns of a `PlaylistRow` with its owner's name and dump count,
- * and the `FROM playlists p` they come from.
+ * The select list and `FROM` clause of a playlist query, adding the owner's
+ * name and the dump count. Callers append the `WHERE`. The dump count includes
+ * dumps the viewer can't see.
  */
 const PLAYLIST_SELECT = `p.*, u.username as owner_username,
    (SELECT COUNT(*) FROM playlist_dumps pd WHERE pd.playlist_id = p.id) as dump_count
    FROM playlists p LEFT JOIN users u ON u.id = p.user_id`;
 
 /**
- * Returns the playlist with id or slug `idOrSlug`, private or not: callers
- * that show it check its visibility.
+ * Returns the playlist with id or slug `idOrSlug`, private or not. A caller
+ * that shows it to someone must check `isPublic` first, as the OG middleware
+ * does.
  *
  * @throws {APIException} 404 when there is no such playlist.
  */
@@ -66,8 +69,9 @@ export function getPlaylistById(idOrSlug: string): Playlist {
 }
 
 /**
- * Creates a playlist owned by `userId`, notifies anyone @mentioned in its
- * description, and announces it.
+ * Creates a playlist owned by `userId`, for `POST /api/playlists`. It notifies
+ * the users its description mentions, links the attachments it embeds, and
+ * broadcasts `playlist_created`.
  */
 export function createPlaylist(
   req: CreatePlaylistRequest,
@@ -107,9 +111,11 @@ export function createPlaylist(
 
 /**
  * Returns a playlist with the dumps `requestingUserId` may see in it, in
- * order.
+ * order, for `GET /api/playlists/:playlistId`. A null `requestingUserId` is a
+ * signed-out viewer.
  *
- * @throws {APIException} 404 when there is no such playlist, or it is private and not theirs.
+ * @throws {APIException} 404 when there is no such playlist, or it is private
+ * and not theirs.
  */
 export function getPlaylist(
   playlistId: string,
@@ -141,7 +147,8 @@ export function getPlaylist(
 
 /**
  * Returns up to `limit` playlists whose title or description contains
- * `query`, newest first: the public ones, and the requesting user's own.
+ * `query`, newest first, for `GET /api/search`. Private playlists are left
+ * out, except `requestingUserId`'s own. A blank `query` finds nothing.
  */
 export function searchPlaylists(
   query: string,
@@ -164,8 +171,9 @@ export function searchPlaylists(
 }
 
 /**
- * Returns a page of `userId`'s playlists, newest first — the private ones only
- * to `userId` themselves.
+ * Returns a page of `userId`'s playlists, newest first, for
+ * `GET /api/users/:username/playlists`. The private ones are listed only when
+ * `requestingUserId` is `userId`.
  */
 export function listPlaylistsByUser(
   userId: string,
@@ -185,11 +193,13 @@ export function listPlaylistsByUser(
 }
 
 /**
- * Applies `req` to a playlist (its slug follows the title), as its owner or a
- * moderator (`canModerate`); notifies anyone @mentioned in the description,
- * and announces the change.
+ * Applies `req` to a playlist for `PUT /api/playlists/:playlistId`, and returns
+ * it as it now is. The slug follows the title. `canModerate` lets someone
+ * other than the owner edit it. It notifies the users the description
+ * mentions, links its attachments and broadcasts `playlist_updated`.
  *
- * @throws {APIException} 404 when there is no such playlist, 403 when the user is neither its owner nor a moderator.
+ * @throws {APIException} 404 when there is no such playlist, 403 when the user
+ * is neither its owner nor a moderator.
  */
 export function updatePlaylist(
   playlistId: string,
@@ -247,10 +257,11 @@ export function updatePlaylist(
 }
 
 /**
- * Deletes a playlist, as its owner or a moderator (`canModerate`), and
- * announces it.
+ * Deletes a playlist for `DELETE /api/playlists/:playlistId`, and broadcasts
+ * `playlist_deleted`. `canModerate` lets someone other than the owner do it.
  *
- * @throws {APIException} 404 when there is no such playlist, 403 when the user is neither its owner nor a moderator.
+ * @throws {APIException} 404 when there is no such playlist, 403 when the user
+ * is neither its owner nor a moderator.
  */
 export function deletePlaylist(
   playlistId: string,
@@ -268,9 +279,12 @@ export function deletePlaylist(
 }
 
 /**
- * Returns the playlist, if the requester may edit it.
+ * Returns the playlist if `requestingUserId` may edit it. The cover upload
+ * route checks this before it writes the file, then calls
+ * {@link setPlaylistImage}.
  *
- * @throws {APIException} 404 when there is no such playlist, 403 when the user is neither its owner nor a moderator.
+ * @throws {APIException} 404 when there is no such playlist, 403 when the user
+ * is neither its owner nor a moderator.
  */
 export function getEditablePlaylist(
   playlistId: string,
@@ -285,10 +299,12 @@ export function getEditablePlaylist(
 }
 
 /**
- * Records a playlist's new cover image and announces it. Call once the image
- * file is in place: this is what announces it.
+ * Records the type of a playlist's new cover and broadcasts `playlist_updated`.
+ * The route must have written the file already, since clients fetch the cover
+ * as soon as they get the broadcast.
  *
- * @throws {APIException} 404 when there is no such playlist, 403 when the user is neither its owner nor a moderator.
+ * @throws {APIException} 404 when there is no such playlist, 403 when the user
+ * is neither its owner nor a moderator.
  */
 export function setPlaylistImage(
   playlistId: string,
@@ -301,8 +317,8 @@ export function setPlaylistImage(
     requestingUserId,
     canModerate,
   );
-  // A new cover is an edit: bumping updated_at also moves the `?v=` the
-  // client puts on the image URL, so a cached old cover isn't shown.
+  // updated_at is the `?v=` the client puts on the cover URL, so bumping it
+  // keeps browsers from showing the cached old cover.
   db.prepare(
     `UPDATE playlists SET image_mime = ?, updated_at = ? WHERE id = ?;`,
   ).run(imageMime, new Date().toISOString(), playlist.id);
@@ -312,11 +328,15 @@ export function setPlaylistImage(
 }
 
 /**
- * Puts a dump at the top of a playlist, announces the change, and notifies the
- * followers of a public playlist when the dump is public.
+ * Puts a dump at the top of a playlist, for
+ * `POST /api/playlists/:playlistId/dumps/:dumpId`, and broadcasts
+ * `playlist_dumps_updated`. The followers of a public playlist are notified
+ * when the dump is public.
  *
- * @throws {APIException} 404 when there is no such playlist, 403 when the user is neither its owner nor a moderator; 404 when the dump doesn't exist or is
- * someone else's private dump, 409 when it is already in the playlist.
+ * @throws {APIException} 404 when there is no such playlist, or when the dump
+ * doesn't exist or is someone else's private dump, 403 when the user is
+ * neither the playlist's owner nor a moderator, 409 when the dump is already
+ * in it.
  */
 export function addDumpToPlaylist(
   playlistId: string,
@@ -330,8 +350,8 @@ export function addDumpToPlaylist(
     throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
   }
 
-  // Only a dump the requester can see — someone else's private dump would
-  // otherwise land in the playlist and its title in followers' notifications.
+  // Else someone else's private dump would land in the playlist, and its title
+  // in the followers' notifications.
   const dump = db.prepare(
     `SELECT title, is_private, user_id FROM dumps WHERE id = ?;`,
   ).get(dumpId) as
@@ -367,7 +387,7 @@ export function addDumpToPlaylist(
 
   broadcastPlaylistDumpsUpdated(playlist, getCurrentMembers(playlist.id));
 
-  // Followers can't open a private dump, even the owner's own.
+  // Followers can't open a private dump, even one of the owner's own.
   if (playlist.isPublic && !dump.is_private) {
     notifyPlaylistFollowersNewDump(
       playlist.id,
@@ -379,9 +399,12 @@ export function addDumpToPlaylist(
 }
 
 /**
- * Takes a dump out of a playlist, if it is in it, and announces the change.
+ * Takes a dump out of a playlist, for
+ * `DELETE /api/playlists/:playlistId/dumps/:dumpId`, and broadcasts
+ * `playlist_dumps_updated`. A dump that isn't in it is no error.
  *
- * @throws {APIException} 404 when there is no such playlist, 403 when the user is neither its owner nor a moderator.
+ * @throws {APIException} 404 when there is no such playlist, 403 when the user
+ * is neither its owner nor a moderator.
  */
 export function removeDumpFromPlaylist(
   playlistId: string,
@@ -403,8 +426,9 @@ export function removeDumpFromPlaylist(
 }
 
 /**
- * Puts the playlist's members the requester can see in the order of
- * `dumpIds`, and announces the change.
+ * Puts the dumps of a playlist that the requester can see in the order of
+ * `dumpIds`, for `PUT /api/playlists/:playlistId/order`, and broadcasts
+ * `playlist_dumps_updated`.
  *
  * @throws {APIException} 404 when there is no such playlist, 403 when the user
  * is neither its owner nor a moderator, 400 when `dumpIds` isn't exactly the
@@ -422,10 +446,9 @@ export function reorderPlaylist(
     throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
   }
 
-  // The requester orders what they can see — the playlist as GET gives it to
-  // them. A member hidden from them (someone else's dump that went private,
-  // or the owner's private dumps for a moderator) can't be named, so it
-  // keeps its slot and the visible ones are reordered around it.
+  // The requester can only name the dumps GET showed them. A hidden one
+  // (someone else's dump that went private, or the owner's private dump for a
+  // moderator) keeps its slot, and the visible ones are reordered around it.
   const members = getCurrentMembers(playlist.id);
   const visibleIds = members
     .filter((m) => isMemberVisibleTo(m, playlist, requestingUserId))
@@ -462,7 +485,10 @@ export function reorderPlaylist(
 
 /**
  * Returns each of `userId`'s playlists, newest first, and whether it holds
- * dump `dumpId`.
+ * dump `dumpId`, for `GET /api/playlists/by-dump/:dumpId/memberships`. The
+ * client's add-to-playlist modal shows it. The playlists have no dump count.
+ *
+ * @throws {APIException} 500 when a row doesn't parse as a playlist.
  */
 export function getPlaylistMembershipsForDump(
   dumpId: string,
@@ -492,10 +518,10 @@ export function getPlaylistMembershipsForDump(
 }
 
 /**
- * Returns the playlists a dump appears in — the "in collections" counterpart to
- * backlinks. Privacy-filtered like `getRelatedDumps`: public playlists for
- * everyone, plus the requesting user's own private ones. Capped at 20 — a
- * small, bounded list of supporting context.
+ * Returns up to 20 playlists that hold dump `dumpId`, newest first, for
+ * `GET /api/dumps/:dumpId/playlists`. Private playlists are left out, except
+ * `requestingUserId`'s own. The route checks first that the caller may see the
+ * dump.
  */
 export function getPlaylistsForDump(
   dumpId: string,
@@ -512,8 +538,9 @@ export function getPlaylistsForDump(
 }
 
 /**
- * Returns a playlist's id, cover image type and visibility, or undefined
- * without a cover. A private playlist's cover exists only for its owner.
+ * Returns what `GET /api/playlists/:playlistId/image` needs to serve a
+ * playlist's cover, or undefined when it has none. The route serves a private
+ * playlist's cover as private, so no shared cache keeps it.
  *
  * @throws {APIException} 404 when there is no such playlist, or it is private
  * and `requestingUserId` isn't its owner.
@@ -535,7 +562,10 @@ export function getPlaylistImageInfo(
     : undefined;
 }
 
-/** Returns a playlist's members, in order, with what their visibility takes. */
+/**
+ * Returns a playlist's dumps in order, all of them, for the callers to filter
+ * per viewer.
+ */
 function getCurrentMembers(playlistId: string): PlaylistMember[] {
   const rows = db.prepare(
     `SELECT pd.dump_id, d.is_private, d.user_id