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

@@ -1,20 +1,42 @@
+/**
+ * Categories, the admin-managed topics a dump can be filed under, and the
+ * bodies that create and edit them.
+ *
+ * @module
+ */
+
+/** A category, which lists its dumps at `/<slug>`. */
 export interface Category {
+  /** The category's id. */
   id: string;
+  /** The category's URL slug, at the site root. */
   slug: string;
+  /** The category's display name. */
   name: string;
+  /** The category's place in the list, ascending. */
   position: number;
+  /** When the category was created. */
   createdAt: Date;
+  /** When the category was last changed, if ever. */
   updatedAt?: Date;
 }
 
+/** The body of `POST /api/categories`. */
 export interface CreateCategoryRequest {
+  /** The new category's slug. */
   slug: string;
+  /** The new category's display name. */
   name: string;
+  /** Its place in the list; 0 when left out. */
   position?: number;
 }
 
+/** The body of `PUT /api/categories/:id`: the fields to change. */
 export interface UpdateCategoryRequest {
+  /** The new slug. */
   slug?: string;
+  /** The new display name. */
   name?: string;
+  /** The new place in the list. */
   position?: number;
 }