v3: comments say what the code can't — the documentation pass wanted JSDoc on every export and every field of an exported interface, which filled the code with restatements ("The dump.", "Whether it is loading.", "The props of X.", "Renders the X.") and module docs that told a reader nothing ("The hot and new feeds, and the props every main feed of the index takes."); some were wrong as well as vague. Every comment in api/, shared/ and src/ is rewritten under one rule, now stated in the README's "Comments" section: every module and export still has a JSDoc, and it gives context (who uses it and where), usage (what a caller must know: a precondition, what it leaves to the caller, a side effect) or its place in the chain (where its input comes from, where its output goes); a field, parameter, private function or local gets one only when it adds to its parent's, and context about a whole type goes on the type; a type's doc is phrased from the value's side ("Returned to Y by X when Z", "Passed to Y by X"); full sentences, as short as they can be, no label-colon-list; // goes wherever the code isn't obvious and says why, and the section banners and narration go. Every claim was checked against the code, which turned up some forty comments that were wrong: DumpCard's claimed it was only used by the hot and new feeds, the WebSocket welcome claimed to be a socket's first message (presence comes first), UpdateUserRequest said null removes a description (it keeps it), deletedDumpIds leaves out that it also holds dumps made private, THEME_COLOR claimed to mirror index.html's, and the like. The routers' JSDoc now says where they are mounted and what becomes of a thrown APIException. doc-lint.ts lets a field without a doc through; a module or export without one still fails. No code changes; 204 backend and 628 frontend tests pass, and doc:lint, deno check, deno lint and tsc are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

api/services/comment-service.ts

@@ -1,5 +1,7 @@
 /**
- * Comments on dumps, threaded by `parent_id`.
+ * Stores the comments on dumps, threaded by `parent_id`. The comment routes
+ * call it and broadcast what it returns. It leaves checking that the caller
+ * may see the dump to them.
  *
  * @module
  */
@@ -17,12 +19,11 @@ import {
 import { linkAttachments } from "./attachment-service.ts";
 import { relinkBacklinks } from "./backlink-service.ts";
 
-/** The columns of a full `CommentRow`, from `comments c` and `users u`. */
+/** The select list of a `CommentRow`, from `comments c` joined to `users u`. */
 const SELECT_COLS =
   `c.id, c.dump_id, c.user_id, c.parent_id, c.body, c.created_at, c.updated_at, c.deleted, c.like_count,
   u.username as author_username, u.avatar_mime as author_avatar_mime`;
 
-/** Returns comment `commentId`, or throws a 404. */
 function fetchComment(commentId: string): Comment {
   const row = db.prepare(
     `SELECT ${SELECT_COLS} FROM comments c JOIN users u ON c.user_id = u.id WHERE c.id = ?;`,
@@ -41,7 +42,8 @@ function fetchComment(commentId: string): Comment {
 }
 
 /**
- * Returns the id of the dump comment `commentId` is posted under.
+ * Returns the id of the dump comment `commentId` is posted under. The likers
+ * route uses it to check that the caller may see that dump.
  *
  * @throws {APIException} 404 when there is no such comment.
  */
@@ -56,8 +58,11 @@ export function getCommentDumpId(commentId: string): string {
 }
 
 /**
- * Returns every comment on dump `dumpId`, deleted ones included, oldest
- * first.
+ * Returns every comment on dump `dumpId`, oldest first, for
+ * `GET /api/dumps/:dumpId/comments`. Deleted comments are included, emptied,
+ * so the client can keep their replies in place.
+ *
+ * @throws {APIException} 500 when a row doesn't parse as a comment.
  */
 export function getComments(dumpId: string): Comment[] {
   const rows = db.prepare(
@@ -75,9 +80,10 @@ export function getComments(dumpId: string): Comment[] {
 }
 
 /**
- * Posts a comment on dump `dumpId`, replying to `parentId` if given; notifies
- * the dump's poster and anyone @mentioned, and binds its attachments and
- * backlinks.
+ * Posts a comment on dump `dumpId`, replying to `parentId` if given, for
+ * `POST /api/dumps/:dumpId/comments`. It notifies the dump's poster and the
+ * users it mentions, and links the comment's attachments and backlinks.
+ * `parentId` isn't checked to be a comment on the same dump.
  */
 export function createComment(
   dumpId: string,
@@ -109,8 +115,10 @@ export function createComment(
 }
 
 /**
- * Replaces a comment's body, as its author or a moderator (`canModerate`);
- * notifies anyone newly @mentioned, and rebinds its attachments and backlinks.
+ * Replaces a comment's body, for `PATCH /api/comments/:commentId`.
+ * `canModerate` lets someone other than the author do it. It notifies the users
+ * it mentions for the first time and relinks the attachments and backlinks. The
+ * route broadcasts the comment unless `isPrivate`.
  *
  * @throws {APIException} 404 when there is no such comment, 400 when it is
  * deleted, 401 when the user is neither its author nor a moderator.
@@ -169,9 +177,10 @@ export function updateComment(
 }
 
 /**
- * Deletes a comment, as its author or a moderator (`canModerate`): its body is
- * emptied and its backlinks dropped, but the row stays so its replies keep
- * their place.
+ * Deletes a comment, for `DELETE /api/comments/:commentId`. `canModerate` lets
+ * someone other than the author do it. The body is emptied and the backlinks
+ * dropped, but the row stays so its replies keep their place. The route
+ * broadcasts the deletion unless `isPrivate`.
  *
  * @throws {APIException} 404 when there is no such comment, 401 when the user
  * is neither its author nor a moderator.