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

@@ -1,8 +1,23 @@
+/**
+ * Dumps — the links and files users post — their link previews, and the bodies
+ * that post and edit them.
+ *
+ * @module
+ */
+
+/** What a link's page says about itself, as its preview card shows it. */
 export interface RichContent {
+  /**
+   * Which provider read it: `youtube`, `bandcamp`, `soundcloud` or `generic`.
+   */
   type: string;
+  /** The link the preview is of. */
   url: string;
+  /** The site's name. */
   siteName?: string;
+  /** The page's title. */
   title?: string;
+  /** The page's description. */
   description?: string;
   /**
    * A real preview image (og:image, a large content image, a video still).
@@ -14,28 +29,49 @@ export interface RichContent {
   faviconUrl?: string;
   /** The page's declared brand color, normalized to `#rrggbb`. */
   accentColor?: string;
+  /** The YouTube video's id, for a YouTube link. */
   videoId?: string;
+  /** The URL of the page's embeddable player, if it has one. */
   embedUrl?: string;
 }
 
+/** A dump: a link or a file a user posted. */
 export interface Dump {
+  /** The dump's id. */
   id: string;
+  /** `url` for a link, `file` for an upload. */
   kind: "url" | "file";
+  /** The dump's title. */
   title: string;
+  /** The dump's URL slug. */
   slug?: string;
+  /** The poster's description, in Markdown. */
   comment?: string;
+  /** The poster's id. */
   userId: string;
+  /** When the dump was posted. */
   createdAt: Date;
+  /** When the dump was last edited, if ever. */
   updatedAt?: Date;
+  /** The link, for a URL dump. */
   url?: string;
+  /** The link's preview, for a URL dump. */
   richContent?: RichContent;
+  /** The uploaded file's name, for a file dump. */
   fileName?: string;
+  /** The uploaded file's type, for a file dump. */
   fileMime?: string;
+  /** The uploaded file's size in bytes, for a file dump. */
   fileSize?: number;
+  /** How many users upvoted the dump. */
   voteCount: number;
+  /** How many comments it has, not counting deleted ones. */
   commentCount: number;
+  /** Whether only the poster sees the dump. */
   isPrivate: boolean;
+  /** The uploaded thumbnail's type, undefined without one. */
   thumbnailMime?: string;
+  /** The ids of the categories it is filed under. */
   categoryIds?: string[];
 }
 
@@ -45,12 +81,19 @@ export interface Dump {
  * `findDumpsByUrl`.
  */
 export interface DumpUrlMatch {
+  /** The dump's id. */
   id: string;
+  /** The dump's URL slug. */
   slug?: string;
+  /** The dump's title. */
   title: string;
+  /** The poster's name. */
   username: string;
+  /** When the dump was posted. */
   createdAt: Date;
+  /** How many users upvoted the dump. */
   voteCount: number;
+  /** How many comments it has. */
   commentCount: number;
 }
 
@@ -60,29 +103,42 @@ export interface DumpUrlMatch {
  * page has no preview" from "this link is dead".
  */
 export interface LinkPreview {
+  /** Whether the page could be fetched. */
   reached: boolean;
+  /** The preview, null when there is none at all. */
   richContent: RichContent | null;
 }
 
+/** The JSON body of `POST /api/dumps`, which posts a link. */
 export interface CreateUrlDumpRequest {
+  /** The link. */
   url: string;
   /** Overrides the title scraped from the page — the poster edited the preview. */
   title?: string;
+  /** The poster's description, in Markdown. */
   comment?: string;
+  /** Whether only the poster will see it. */
   isPrivate?: boolean;
+  /** The ids of the categories to file it under. */
   categoryIds?: string[];
 }
 
+/** The body of `PUT /api/dumps/:dumpId`: the fields to change. */
 export interface UpdateDumpRequest {
+  /** The new link, for a URL dump. */
   url?: string;
+  /** The new title. */
   title?: string;
   /** `null` removes the note; leaving it out keeps it. */
   comment?: string | null;
+  /** Whether only the poster will see it. */
   isPrivate?: boolean;
+  /** The ids of the categories to file it under, replacing the current ones. */
   categoryIds?: string[];
 }
 
 /** `POST /api/attachments`: the id the uploaded image is served under. */
 export interface AttachmentResponse {
+  /** The attachment's id, for `GET /api/attachments/:attachmentId`. */
   id: string;
 }