v3: shared/ is documented like api/ — deno doc --lint over api/ and shared/ goes from 385 errors to none — every module of shared/ opens with a /** … @module */ block; every export and every field of an exported interface has JSDoc, each request body naming the endpoint that takes it and each response its endpoint; the // comments that described declarations (the mention pattern, the permission union and table, four socket messages, the error message's optimistic-action context) are /** */ now, and the socket protocol's heading comment, which sat on no declaration, is its module doc. The lint wanted explicit types on MENTION_RE and DUMP_MAX_FILE_SIZE_BYTES. Along the way: the chat edit is allowed to moderators too, which the new ChatEditMessage doc says; UpdateUserRequest says that PATCH /api/users/me takes only its description and email; playlist-service's reorderPlaylist @throws is rewrapped. mod.ts and the README no longer call shared/ undocumented. No behaviour changes; 205 backend tests pass.

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

shared/playlist.ts

@@ -1,40 +1,80 @@
+/**
+ * Playlists — ordered collections of dumps — and the bodies that create, edit
+ * and reorder them.
+ *
+ * @module
+ */
+
 import type { Dump } from "./dump.ts";
 
+/** A playlist. */
 export interface Playlist {
+  /** The playlist's id. */
   id: string;
+  /** The owner's id. */
   userId: string;
+  /** The playlist's title. */
   title: string;
+  /** The playlist's URL slug. */
   slug?: string;
+  /** The owner's description, in Markdown. */
   description?: string;
+  /** Whether anyone may see it, or only its owner. */
   isPublic: boolean;
+  /** When the playlist was created. */
   createdAt: Date;
+  /** When the playlist was last changed, if ever. */
   updatedAt?: Date;
+  /** The cover image's type, undefined without one. */
   imageMime?: string;
+  /**
+   * How many dumps it holds, private ones included, where the query counts
+   * them.
+   */
   dumpCount?: number;
+  /** The owner's name, where the query joins it. */
   ownerUsername?: string;
 }
 
+/** A playlist with the dumps the caller may see in it, in order. */
 export interface PlaylistWithDumps extends Playlist {
+  /** The dumps, in the playlist's order. */
   dumps: Dump[];
 }
 
+/**
+ * `GET /api/playlists/by-dump/:dumpId/memberships`: one of the caller's
+ * playlists, and whether it holds the dump.
+ */
 export interface PlaylistMembership {
+  /** The playlist. */
   playlist: Playlist;
+  /** Whether it holds the dump. */
   hasDump: boolean;
 }
 
+/** The body of `POST /api/playlists`. */
 export interface CreatePlaylistRequest {
+  /** The new playlist's title. */
   title: string;
+  /** Its description, in Markdown. */
   description?: string;
+  /** Whether anyone may see it. */
   isPublic: boolean;
 }
 
+/** The body of `PUT /api/playlists/:playlistId`: the fields to change. */
 export interface UpdatePlaylistRequest {
+  /** The new title. */
   title?: string;
+  /** The new description; `null` removes it. */
   description?: string | null;
+  /** Whether anyone may see it. */
   isPublic?: boolean;
 }
 
+/** The body of `PUT /api/playlists/:playlistId/order`. */
 export interface ReorderPlaylistRequest {
+  /** Every dump of the playlist the caller can see, in the new order. */
   dumpIds: string[];
 }