v3: every doc opens with the role, then the mechanism, then the details — the docs were written bottom-up: what a thing does first ("Declares the three contexts WSProvider fills…"), details that only make sense once its purpose is known next, and the reason it exists last ("…so that a feed doesn't re-render"), so a reader had nothing to hang the first sentences on. The README's rule caused it, since a module doc "opened with what the module does"; it now opens with the module's role in the app, and the value-side phrasing of a type ("Returned to Y by X") comes once the role is said, with WSContext as the before and after. WSContext.ts is rewritten that way throughout, and so are the docs elsewhere that buried their purpose in a trailing "so that" (the migrations, og, image-proxy, public-address, useFading, useFeedCache, the drafts), opened on a generic verb that hid it ("Holds", "Declares", "Loads", "Defines", "Types": the contexts and providers, the shared types, the models, the hooks), or were label fragments ("The page of a dump…", "A row of tabs."). A function whose verb is its action ("Stores session"), a props or result type, and a protocol message ("Sent by X when Y") already say their role and are left as they are. Only comments changed, and the catalogs only move their references; deno fmt, deno lint and doc:lint are clean.

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

api/config.ts

@@ -1,7 +1,8 @@
 /**
- * Reads the server's settings from the `GERBEUR_*` environment variables, once
- * at import, and holds the fixed limits the backend applies. The deno tasks
- * load `.env` with `--env-file`, so changing a setting needs a restart.
+ * Lets a deployment configure the server through the `GERBEUR_*` environment
+ * variables, which it reads once at import, and holds the fixed limits the
+ * backend applies. The deno tasks load `.env` with `--env-file`, so changing a
+ * setting needs a restart.
  *
  * @module
  */
@@ -55,10 +56,10 @@ export const PUBLIC_URL: string =
   Deno.env.get("GERBEUR_PUBLIC_URL")?.trim().replace(/\/$/, "") ||
   `http://localhost:${PORT}`;
 /**
- * Holds the URL the frontend is served from (`GERBEUR_FRONTEND_URL`), without
- * a trailing slash, when it isn't {@link PUBLIC_URL}, as with a separate Vite
- * server. It is an allowed origin, and password reset links and the Open Graph
- * tags' page URLs point to it.
+ * Points password reset links and the Open Graph tags' page URLs at the
+ * frontend when it isn't served from {@link PUBLIC_URL}, as with a separate
+ * Vite server, and allows it as an origin. It is `GERBEUR_FRONTEND_URL`,
+ * without a trailing slash.
  */
 export const FRONTEND_URL: string =
   Deno.env.get("GERBEUR_FRONTEND_URL")?.trim().replace(/\/$/, "") ||

api/db/migrations/0002_dump_thumbnail.ts

@@ -1,7 +1,7 @@
 /**
- * Adds `dumps.custom_thumbnail_mime`, so a poster can upload a thumbnail that
- * replaces the fetched one. It holds the uploaded image's type, and NULL means
- * the dump has none.
+ * Lets a poster upload a thumbnail that replaces the fetched one. It adds
+ * `dumps.custom_thumbnail_mime`, which holds the uploaded image's type; NULL
+ * means the dump has none.
  *
  * @module
  */

api/db/migrations/0003_dump_backlinks.ts

@@ -1,8 +1,8 @@
 /**
- * Adds `dump_backlinks`, which records the links from a dump's note or
- * comments to other dumps, so a dump page can list the dumps related to it.
- * backlink-service fills it, and the index on `dumps.url` lets it find the
- * dumps an external link was posted as.
+ * Lets a dump page list the dumps related to it. It adds `dump_backlinks`,
+ * which records the links from a dump's note or comments to other dumps and
+ * which backlink-service fills, and an index on `dumps.url` to find the dumps
+ * an external link was posted as.
  *
  * @module
  */

api/db/migrations/0004_user_roles.ts

@@ -1,6 +1,6 @@
 /**
- * Adds `users.role`, which replaces the `is_admin` flag so that moderators can
- * exist between users and admins. 0005 then drops the flag.
+ * Makes room for moderators between users and admins. It adds `users.role`,
+ * which replaces the `is_admin` flag, and 0005 then drops the flag.
  *
  * @module
  */

api/db/migrations/0009_chat_reply.ts

@@ -1,8 +1,8 @@
 /**
- * Adds `chat_messages.reply_to_id`, so a message can reply to another. It has
- * no foreign key on purpose: when the replied-to message is deleted, the id
- * stays and chat-service's join reads null, so the chat shows "deleted
- * message" where the quote was.
+ * Lets a chat message reply to another, through `chat_messages.reply_to_id`.
+ * The column has no foreign key on purpose: when the replied-to message is
+ * deleted, the id stays and chat-service's join reads null, so the chat shows
+ * "deleted message" where the quote was.
  *
  * @module
  */

api/db/migrations/0010_youtube_embed_start.ts

@@ -1,8 +1,8 @@
 /**
- * Adds the `start` parameter to the YouTube embed URLs stored before the
- * YouTube provider carried it over. `rich_content.embedUrl` is computed when a
- * dump is posted, and used to drop the source URL's `t` (`?t=1265`,
- * `?t=1h2m3s`), so those videos played from 0:00.
+ * Makes the YouTube dumps posted with a start time, before the YouTube provider
+ * kept it, start there instead of at 0:00. `rich_content.embedUrl` is computed
+ * when a dump is posted, and it used to drop the source URL's `t` (`?t=1265`,
+ * `?t=1h2m3s`); this adds the `start` parameter back to the stored embed URLs.
  *
  * It reads the time from the stored source URL and fetches nothing. It keeps
  * its own copy of the parsing, so that it migrates every database alike should

api/db/migrations/0011_split_favicon_thumbnail.ts

@@ -1,10 +1,11 @@
 /**
- * Moves site icons out of `rich_content.thumbnailUrl` into the new
- * `faviconUrl`. The metadata fetch used to fall back on the page's icon, and
- * then on a guessed `/favicon.ico`, so most thumbnails were a 16×16 icon, or a
- * 404, that the UI stretched over a 128×72 box. It now stops at real artwork,
- * and a missing `thumbnailUrl` means none, which the frontend draws a
- * placeholder for. This gives the older rows that meaning.
+ * Stops older dumps from showing a site's icon as their thumbnail. The metadata
+ * fetch used to fall back on the page's icon, and then on a guessed
+ * `/favicon.ico`, so most thumbnails were a 16×16 icon, or a 404, that the UI
+ * stretched over a 128×72 box. It now stops at real artwork, and a missing
+ * `thumbnailUrl` means none, which the frontend draws a placeholder for. This
+ * gives the older rows that meaning, by moving their icons out of
+ * `rich_content.thumbnailUrl` into the new `faviconUrl`.
  *
  * It judges the stored URL alone and fetches nothing, so it doesn't fill
  * `accentColor`. The frontend derives a hue from the hostname when it is

api/db/migrations/0013_dump_url_canonical.ts

@@ -1,6 +1,7 @@
 /**
- * Adds `dumps.url_canonical`, the key the create form's "already dumped" hint
- * looks a URL up by, and fills it for every URL dump already posted.
+ * Lets the create form warn that a link was already dumped. It adds
+ * `dumps.url_canonical`, the key the hint looks a URL up by, and fills it for
+ * every URL dump already posted.
  *
  * It fills the key from each stored URL and fetches nothing. Its helpers are a
  * copy of lib/canonical-url.ts as it stood when this shipped: importing the

api/db/migrations/0015_token_revocation.ts

@@ -1,7 +1,7 @@
 /**
- * Adds `users.tokens_valid_after`, so that changing a password ends every
- * session opened before. Tokens are stateless JWTs, so lib/auth.ts refuses a
- * token issued before that time instead.
+ * Lets a password change end every session opened before it. Tokens are
+ * stateless JWTs, so this adds `users.tokens_valid_after`, and lib/auth.ts
+ * refuses a token issued before that time.
  *
  * @module
  */

api/db/migrations/0018_attachment_resource_type.ts

@@ -1,8 +1,10 @@
 /**
- * Adds `attachments.resource_type`, the kind of thing an attachment's
- * `resource_id` names. Without it, an attachment couldn't tell whose it was:
- * one pasted into a private dump was served to anyone with its URL, and one
- * whose dump, comment or message was deleted was kept for good.
+ * Serves an attachment only to those who may see what it was pasted into, and
+ * deletes it once that is gone. It adds `attachments.resource_type`, the kind
+ * of thing an attachment's `resource_id` names. Without it, an attachment
+ * couldn't tell whose it was: one pasted into a private dump was served to
+ * anyone with its URL, and one whose dump, comment or message was deleted was
+ * kept for good.
  *
  * @module
  */

api/lib/api-exception.ts

@@ -1,6 +1,6 @@
 /**
- * Defines the exception that carries an HTTP error from any layer up to the
- * error middleware.
+ * Lets any layer fail a request with an HTTP status, which the error middleware
+ * turns into the response.
  *
  * @module
  */

api/lib/canonical-url.ts

@@ -1,9 +1,10 @@
 /**
- * Reduces a URL to a key shared by every link to the same page or video.
- * `dump-service` stores it in `dumps.url_canonical` when a
- * dump is posted or edited, and `GET /api/dumps/by-url` matches on it
- * to warn the create form of a repost. The key is never fetched or shown, so it
- * may be lossy: it forces `https`, drops `www.`, tracking parameters and
+ * Spots reposts and links to known dumps, by reducing a URL to a key shared by
+ * every link to the same page or video. `dump-service` stores it in
+ * `dumps.url_canonical` when a dump is posted or edited, `GET
+ * /api/dumps/by-url` matches on it to warn the create form of a repost, and
+ * backlink-service compares links by it. The key is never fetched or shown, so
+ * it may be lossy: it forces `https`, drops `www.`, tracking parameters and
  * timestamps.
  *
  * Migration 0013 backfilled existing rows with a frozen copy of these rules.

api/lib/pagination.ts

@@ -1,7 +1,7 @@
 /**
- * Reads the page a list route's query string asks for, and cuts the rows a
- * service fetched into that page. The routes send the page as
- * `PaginatedData`.
+ * Pages every list route the same way. It reads the page a list route's query
+ * string asks for, and cuts the rows a service fetched into that page, which
+ * the routes send as `PaginatedData`.
  *
  * @module
  */

api/middleware/og.ts

@@ -1,8 +1,8 @@
 /**
- * Answers a link to a dump, a profile or a public playlist with `index.html`
- * carrying that page's Open Graph and Twitter card tags, for the link previews
- * of chat apps and social sites, which don't run the app. main.ts installs it
- * before the routers.
+ * Gives links to the site rich previews in chat apps and social sites, which
+ * don't run the app. It answers a link to a dump, a profile or a public
+ * playlist with `index.html` carrying that page's Open Graph and Twitter card
+ * tags. main.ts installs it before the routers.
  *
  * @module
  */

api/model/auth.ts

@@ -1,6 +1,7 @@
 /**
- * Types the payloads of session and password reset tokens, and guards them.
- * `lib/jwt.ts` signs the tokens and runs the guards when it verifies one.
+ * Checks what a verified token says before it is trusted. It types the payloads
+ * of session and password reset tokens, and `lib/jwt.ts` runs their guards when
+ * it verifies one.
  *
  * @module
  */

api/model/category.ts

@@ -1,6 +1,6 @@
 /**
- * Types the rows the category service reads from `categories`, and turns them
- * into the {@link Category} the category routes send.
+ * Turns the rows the category service reads from `categories` into the {@link
+ * Category} the category routes send.
  *
  * @module
  */

api/model/chat.ts

@@ -1,5 +1,5 @@
 /**
- * Maps the rows of `chat_messages` to the {@link ChatMessage} the API sends.
+ * Turns the rows of `chat_messages` into the {@link ChatMessage} the API sends.
  * Only `services/chat-service.ts` uses it, on the rows of its one query.
  *
  * @module

api/model/comment.ts

@@ -1,6 +1,6 @@
 /**
- * Types the rows the comment service reads from `comments`, and turns them into
- * the {@link Comment} the comment routes send.
+ * Turns the rows the comment service reads from `comments` into the {@link
+ * Comment} the comment routes send.
  *
  * @module
  */

api/model/dump.ts

@@ -1,7 +1,8 @@
 /**
- * Maps the `dumps` table to the API's {@link Dump}. Every service that reads
- * dumps selects them with the column lists here, checks each row with
- * {@link isDumpRow} and converts it with {@link dumpRowToApi}.
+ * Turns the rows of `dumps` into the API's {@link Dump} the same way for every
+ * service that reads dumps: each selects them with the column lists here,
+ * checks each row with {@link isDumpRow} and converts it with {@link
+ * dumpRowToApi}.
  *
  * @module
  */

api/model/follow.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `follows`, which `follow-service.ts` reads to
- * answer what a user follows.
+ * Checks the rows `follow-service.ts` reads from `follows` to answer what a
+ * user follows.
  *
  * @module
  */

api/model/invite.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `invites`, which `invite-service.ts` reads to
- * check an invite before sign-up.
+ * Checks the rows `invite-service.ts` reads from `invites` to vet an invite
+ * before sign-up.
  *
  * @module
  */

api/model/notification.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `notifications`, and converts them to the
- * {@link Notification} that `GET /api/notifications` answers.
+ * Turns the rows of `notifications`, once checked, into the {@link
+ * Notification} that `GET /api/notifications` answers.
  *
  * @module
  */

api/model/password-reset.ts

@@ -1,6 +1,6 @@
 /**
- * Types and guards the rows of `password_reset_tokens`, which
- * `password-reset-service.ts` reads to make each reset link work once.
+ * Checks the rows `password-reset-service.ts` reads from
+ * `password_reset_tokens` to make each reset link work once.
  *
  * @module
  */

api/model/playlist.ts

@@ -1,6 +1,6 @@
 /**
- * Types the rows the playlist and follow services read from `playlists`, and
- * turns them into the {@link Playlist} the API sends.
+ * Turns the rows the playlist and follow services read from `playlists` into
+ * the {@link Playlist} the API sends.
  *
  * @module
  */

api/model/rows.ts

@@ -1,7 +1,6 @@
 /**
- * Checks the rows of a list query, for the services. Every service answers a
- * row that doesn't have its table's shape with a 500 rather than leaving it
- * out, so that damage shows instead of making items silently vanish.
+ * Makes a damaged row fail its query with a 500 rather than silently vanish
+ * from a list. Every service checks the rows of its list queries with it.
  *
  * @module
  */

api/model/user.ts

@@ -1,7 +1,7 @@
 /**
- * Types and guards the rows of `users`, and converts them to the {@link User}
- * that `user-service.ts` returns. A route turns a `User` into what it may send
- * with {@link toPublicUser} or {@link toSelfUser}.
+ * Turns the rows of `users`, once checked, into the {@link User} that
+ * `user-service.ts` returns. A route turns a `User` into what it may send with
+ * {@link toPublicUser} or {@link toSelfUser}.
  *
  * @module
  */

api/remote/image-proxy.ts

@@ -1,8 +1,9 @@
 /**
- * Fetches and caches the remote images `GET /api/proxy-image` serves. The
- * frontend routes a thumbnail through it when the image is on plain http,
- * which an https page would block, or when loading it directly failed, often
- * to hotlink protection.
+ * Shows the thumbnails a browser can't load from their own site: those on plain
+ * http, which an https page would block, and those behind hotlink protection.
+ * It fetches and caches the images `GET /api/proxy-image` serves, which the
+ * frontend routes a thumbnail through when it is on http or when loading it
+ * directly failed.
  *
  * @module
  */

api/remote/providers/provider.ts

@@ -1,6 +1,7 @@
 /**
- * Declares what a link provider implements. `rich-content-service.ts` asks its
- * providers in turn and fetches a link's preview from the first that matches.
+ * Lets each kind of site have its own link previews. A provider implements this
+ * interface, and `rich-content-service.ts` asks its providers in turn and
+ * fetches a link's preview from the first that matches.
  *
  * @module
  */

api/remote/public-address.ts

@@ -1,8 +1,8 @@
 /**
- * Tells private addresses from public ones, so that a user-supplied URL can't
- * make the server fetch what only it can reach: loopback, the LAN, container
- * networks or the cloud metadata endpoint at 169.254.169.254. `fetch.ts` checks
- * every hop with it.
+ * Keeps a user-supplied URL from making the server fetch what only it can
+ * reach: loopback, the LAN, container networks or the cloud metadata endpoint
+ * at 169.254.169.254. It tells private addresses from public ones, and
+ * `fetch.ts` checks every hop with it.
  *
  * @module
  */

api/remote/youtube-playlist.ts

@@ -1,7 +1,7 @@
 /**
- * Resolves a YouTube playlist to its entries' titles and lengths, for
- * `GET /api/youtube/playlist`. The embed plays the list but doesn't expose
- * them, and the global player needs them to draw a tracklist.
+ * Gives the global player a tracklist for a YouTube playlist, which the embed
+ * plays but doesn't list. It resolves the playlist to its entries' titles and
+ * lengths, for `GET /api/youtube/playlist`.
  *
  * They are read from the `ytInitialData` JSON of the public playlist page,
  * whose undocumented shape changes, so both the current `lockupViewModel` rows

api/routes/avatars.ts

@@ -1,7 +1,7 @@
 /**
- * Serves the avatar endpoints. The profile page uploads the avatar, and the
- * client's `Avatar` component loads it, with the user's `updatedAt` as a
- * cache-busting version.
+ * Stores and serves the users' avatars. The profile page uploads the avatar,
+ * and the client's `Avatar` component loads it, with the user's `updatedAt` as
+ * a cache-busting version.
  *
  * - `POST /api/avatars/me` — signed in. Replaces the caller's avatar (multipart
  *   `file`, at most 5 MB), sends `user_updated` to everyone, and answers the

api/routes/categories.ts

@@ -1,5 +1,6 @@
 /**
- * The category routes.
+ * Serves the categories dumps are filed under and their feeds, and changes them
+ * for those with `category:manage`.
  *
  * - `GET /api/categories` — public. Answers every category, in order.
  * - `GET /api/categories/:slug` — public. Answers one category.

api/routes/invites.ts

@@ -1,6 +1,6 @@
 /**
- * Serves the invite endpoints. Any signed-in user can invite someone, from
- * their profile page, and the invite link opens the `/register` page.
+ * Lets any signed-in user invite someone, from their profile page. The invite
+ * link opens the `/register` page.
  *
  * - `POST /api/invites` — signed in. Makes an invite and answers its token.
  * - `GET /api/invites/:token` — public. Checks that an invite still works,

api/routes/thumbnails.ts

@@ -31,8 +31,8 @@ import { authenticateMedia } from "../lib/auth.ts";
 const router: Router = new Router({ prefix: "/api/thumbnails" });
 
 /**
- * Holds whether ffmpeg runs, probed once per process: probing on every uncached
- * thumbnail request cost a process per card.
+ * Spares a process per uncached thumbnail request: whether ffmpeg runs is
+ * probed once per process, and kept here.
  */
 let ffmpegProbe: Promise<boolean> | undefined;
 
@@ -146,8 +146,8 @@ function imagePreview(srcPath: string, outPath: string): Promise<void> {
 }
 
 /**
- * Holds the generations under way, by output path. A feed full of cards asking
- * for the same new still at once then waits on a single ffmpeg run.
+ * Lets a feed full of cards asking for the same new still at once wait on a
+ * single ffmpeg run. It holds the generations under way, by output path.
  */
 const inFlight = new Map<string, Promise<void>>();
 

api/services/attachment-service.ts

@@ -1,7 +1,8 @@
 /**
- * Records the images pasted into Markdown bodies, and binds each one to the
- * resource whose body links it. `routes/attachments.ts` stores and serves the
- * files; the services that save a body call {@link linkAttachments}.
+ * Ties each image pasted into a Markdown body to the dump, comment, playlist or
+ * message that links it, so the image is served only to those who may see that,
+ * and purged at startup once it is gone. `routes/attachments.ts` stores and
+ * serves the files; the services that save a body call {@link linkAttachments}.
  *
  * @module
  */

api/services/rich-content-service.ts

@@ -52,9 +52,9 @@ const RECENT_TTL_MS = 5 * 60 * 1000;
 /** How many previews are kept. The oldest written goes first. */
 const RECENT_MAX = 200;
 /**
- * Holds the previews fetched in the last few minutes, by URL. The create form
- * previews a link and then posts it, and without this the second fetch of the
- * page was the slow part of posting. Only successes are kept.
+ * Makes posting a link fast after the create form previewed it, by keeping the
+ * previews fetched in the last few minutes, by URL. Without it, the second
+ * fetch of the page was the slow part of posting. Only successes are kept.
  */
 const recent = new Map<
   string,