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

@@ -1,39 +1,66 @@
 /**
- * The envelope every endpoint answers with, and the error codes it carries.
+ * The envelope every endpoint answers with, the error codes it carries, the
+ * shape of a paginated list, and {@link Wire}, which maps a type to what JSON
+ * makes of it.
+ *
+ * @module
  */
 
+/** The error codes an {@link APIError} carries, by name. */
 export const APIErrorCode = {
+  /** The request is malformed or not allowed in the current state. */
   BAD_REQUEST: "BAD_REQUEST",
+  /** What the request names doesn't exist, or the caller may not see it. */
   NOT_FOUND: "NOT_FOUND",
+  /** The server failed. */
   SERVER_ERROR: "SERVER_ERROR",
+  /** A remote site took too long to answer. */
   TIMEOUT: "TIMEOUT",
+  /** The caller isn't signed in, or may not do this. */
   UNAUTHORIZED: "UNAUTHORIZED",
+  /** The request body failed validation. */
   VALIDATION_ERROR: "VALIDATION_ERROR",
 } as const;
 
+/** One of the {@link APIErrorCode} values. */
 export type APIErrorCode = typeof APIErrorCode[keyof typeof APIErrorCode];
 
+/** What went wrong, in a failed response. */
 export interface APIError {
+  /** The kind of failure. */
   code: APIErrorCode;
+  /** A human-readable explanation. */
   message: string;
 }
 
+/** A successful response, carrying its payload. */
 export interface APISuccess<T> {
+  /** Always true. */
   success: true;
+  /** The payload. */
   data: T;
+  /** Never set on success. */
   error?: never;
 }
 
+/** A failed response, carrying its error. */
 export interface APIFailure {
+  /** Always false. */
   success: false;
+  /** Never set on failure. */
   data?: never;
+  /** What went wrong. */
   error: APIError;
 }
 
+/** What every endpoint answers with, narrowed by `success`. */
 export type APIResponse<T> = APISuccess<T> | APIFailure;
 
+/** One page of a list. */
 export interface PaginatedData<T> {
+  /** The page's items. */
   items: T[];
+  /** Whether another page follows. */
   hasMore: boolean;
   /** The whole list's size — only where it's shown (search results). */
   total?: number;