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/player.ts

@@ -1,41 +1,68 @@
-/** `GET /api/bandcamp/tracks`: a Bandcamp page resolved at play time. */
+/**
+ * What the player's resolvers answer: a Bandcamp release's streams and a
+ * YouTube playlist's tracks.
+ *
+ * @module
+ */
+
+/** A track of a Bandcamp release, as {@link Tralbum} lists it. */
 export interface TralbumTrack {
-  /** Position in the parsed array — the stable handle used to re-resolve a
-   * track after its signed URL expires. */
+  /**
+   * Position in the parsed array — the stable handle used to re-resolve a
+   * track after its signed URL expires.
+   */
   index: number;
+  /** The track's number on the release. */
   trackNum?: number;
+  /** The track's title. */
   title: string;
   /** Seconds, fractional. */
   duration?: number;
+  /** The signed stream URL, null when the track can't be played. */
   streamUrl: string | null;
-  /** False for preorder, unreleased and still-encoding tracks. They stay in
-   * the list so numbering matches the release, but never enter the queue. */
+  /**
+   * False for preorder, unreleased and still-encoding tracks. They stay in
+   * the list so numbering matches the release, but never enter the queue.
+   */
   streamable: boolean;
   /** Bandcamp caps free plays per track; a capped track may serve a clip. */
   capped: boolean;
 }
 
+/** `GET /api/bandcamp/tracks`: a Bandcamp page resolved at play time. */
 export interface Tralbum {
+  /** The page it was resolved from. */
   sourceUrl: string;
+  /** Whether the page is an album or a single track. */
   itemType: "album" | "track";
+  /** The release's title. */
   title?: string;
+  /** The artist's name. */
   artist?: string;
+  /** The release's cover. */
   artworkUrl?: string;
+  /** The release's tracks, in order. */
   tracks: TralbumTrack[];
   /** Epoch ms of the fetch that produced these signed URLs. */
   resolvedAt: number;
 }
 
-/** `GET /api/youtube/playlist`: a playlist's tracklist, for the player. */
+/** A video of a YouTube playlist, as {@link YouTubePlaylist} lists it. */
 export interface YouTubePlaylistTrack {
+  /** The video's id. */
   videoId: string;
+  /** The video's title. */
   title: string;
   /** Seconds. */
   duration?: number;
 }
 
+/** `GET /api/youtube/playlist`: a playlist's tracklist, for the player. */
 export interface YouTubePlaylist {
+  /** The playlist's id. */
   listId: string;
+  /** The playlist's title. */
   title?: string;
+  /** Its videos, in order. */
   tracks: YouTubePlaylistTrack[];
 }