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

@@ -1,3 +1,10 @@
+/**
+ * Notifications: their types, and the data each type carries.
+ *
+ * @module
+ */
+
+/** What a notification is about. */
 export type NotificationType =
   | "playlist_followed"
   | "user_followed"
@@ -8,64 +15,110 @@ export type NotificationType =
   | "dump_commented"
   | "comment_liked";
 
+/** `playlist_followed`: someone followed one of the user's playlists. */
 export interface PlaylistFollowedData {
+  /** The follower's id. */
   followerId: string;
+  /** The follower's name. */
   followerUsername: string;
+  /** The playlist's id. */
   playlistId: string;
+  /** The playlist's title. */
   playlistTitle: string;
 }
 
+/** `user_followed`: someone followed the user. */
 export interface UserFollowedData {
+  /** The follower's id. */
   followerId: string;
+  /** The follower's name. */
   followerUsername: string;
 }
 
+/** `user_dump_posted`: a user they follow posted a dump. */
 export interface UserDumpPostedData {
+  /** The poster's id. */
   dumperId: string;
+  /** The poster's name. */
   dumperUsername: string;
+  /** The dump's id. */
   dumpId: string;
+  /** The dump's title. */
   dumpTitle: string;
 }
 
+/** `playlist_dump_added`: a dump was added to a playlist they follow. */
 export interface PlaylistDumpAddedData {
+  /** The dump's id. */
   dumpId: string;
+  /** The dump's title. */
   dumpTitle: string;
+  /** The playlist's id. */
   playlistId: string;
+  /** The playlist's title. */
   playlistTitle: string;
 }
 
+/** `dump_upvoted`: someone upvoted one of the user's dumps. */
 export interface DumpUpvotedData {
+  /** The voter's id. */
   voterId: string;
+  /** The voter's name. */
   voterUsername: string;
+  /** The dump's id. */
   dumpId: string;
+  /** The dump's title. */
   dumpTitle: string;
 }
 
+/** `user_mentioned`: someone @mentioned the user. */
 export interface UserMentionedData {
+  /** The mentioner's id. */
   mentionerId: string;
+  /** The mentioner's name. */
   mentionerUsername: string;
+  /** Where the mention was written. */
   contextType: "comment" | "dump" | "playlist" | "chat";
+  /** The id of the comment, dump, playlist or chat message. */
   contextId: string;
+  /**
+   * The title of the dump or playlist, or of the dump a comment is under;
+   * empty for the chat.
+   */
   contextTitle: string;
+  /** The dump a comment is under, for a mention in a comment. */
   dumpId?: string;
 }
 
+/** `dump_commented`: someone commented on one of the user's dumps. */
 export interface DumpCommentedData {
+  /** The commenter's id. */
   commenterId: string;
+  /** The commenter's name. */
   commenterUsername: string;
+  /** The comment's id. */
   commentId: string;
+  /** The dump's id. */
   dumpId: string;
+  /** The dump's title. */
   dumpTitle: string;
 }
 
+/** `comment_liked`: someone liked one of the user's comments. */
 export interface CommentLikedData {
+  /** The liker's id. */
   likerId: string;
+  /** The liker's name. */
   likerUsername: string;
+  /** The comment's id. */
   commentId: string;
+  /** The id of the dump it is under. */
   dumpId: string;
+  /** The title of the dump it is under. */
   dumpTitle: string;
 }
 
+/** The data of any notification; its {@link NotificationType} says which. */
 export type NotificationData =
   | PlaylistFollowedData
   | UserFollowedData
@@ -76,11 +129,18 @@ export type NotificationData =
   | DumpCommentedData
   | CommentLikedData;
 
+/** A notification sent to a user. */
 export interface Notification {
+  /** The notification's id. */
   id: string;
+  /** The id of the user it is for. */
   userId: string;
+  /** What it is about. */
   type: NotificationType;
+  /** Its details, shaped by `type`. */
   data: NotificationData;
+  /** Whether the user has read it. */
   read: boolean;
+  /** When it was sent. */
   createdAt: Date;
 }