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>

src/hooks/chat/useChat.ts

@@ -1,5 +1,5 @@
 /**
- * Reads `ChatContext`, for the buttons that open the chat.
+ * Lets a button open the chat, by reading `ChatContext`.
  *
  * @module
  */

src/hooks/dump/useUserDumpFeed.ts

@@ -1,6 +1,6 @@
 /**
- * Loads a user's dumps or upvoted dumps, a page at a time, for the profile
- * subpages that list them in full.
+ * Feeds the profile subpages that list all of a user's dumps, or all they
+ * upvoted, loading them a page at a time.
  *
  * @module
  */

src/hooks/editor/useEmojiTrigger.ts

@@ -1,7 +1,7 @@
 /**
- * Keeps the state of `TextEditor`'s emoji picker, which opens on a typed
- * `:query` or from the editor's button. `TextEditor` renders the picker and
- * handles its keys.
+ * Lets a user insert an emoji by typing `:query` or from the editor's button.
+ * It keeps the state of `TextEditor`'s emoji picker, and `TextEditor` renders
+ * the picker and handles its keys.
  *
  * @module
  */

src/hooks/editor/useMentionAutocomplete.ts

@@ -1,7 +1,7 @@
 /**
- * Keeps the state of `TextEditor`'s `@mention` suggestions, which it fetches
- * from `GET /api/users/search`. `TextEditor` renders them in a
- * `MentionDropdown`.
+ * Suggests users to @mention as the user types in `TextEditor`. It keeps the
+ * state of the suggestions, fetched from `GET /api/users/search`, and
+ * `TextEditor` renders them in a `MentionDropdown`.
  *
  * @module
  */

src/hooks/feed/useDefaultFeedTab.ts

@@ -1,5 +1,6 @@
 /**
- * Stores, in this browser, which feed tab the index opens on.
+ * Lets a user choose which feed tab the index opens on, remembered in this
+ * browser.
  *
  * @module
  */

src/hooks/feed/useFading.ts

@@ -1,6 +1,6 @@
 /**
- * Times the fade-out of items leaving a list, so that a removal made by
- * mistake can be undone before the item is gone.
+ * Lets a removal made by mistake be undone before the item leaves the list, by
+ * timing the fade-out of items leaving a list.
  *
  * @module
  */

src/hooks/feed/useFeedCache.ts

@@ -1,6 +1,7 @@
 /**
- * Keeps a feed's loaded pages and scroll position in sessionStorage, so that
- * going back to a feed page shows it as it was left instead of refetching it.
+ * Shows a feed as it was left when the user comes back to it, instead of
+ * fetching it again. It keeps the feed's loaded pages and scroll position in
+ * sessionStorage.
  *
  * @module
  */

src/hooks/feed/usePagedList.ts

@@ -1,7 +1,7 @@
 /**
- * Loads a list a page at a time. Every list the API pages goes through
- * {@link useLoadMore} for its next pages, and a list that loads on its own
- * through {@link usePagedList}, from its first page on.
+ * Gives every paged list of the app the same loading. Every list the API pages
+ * goes through {@link useLoadMore} for its next pages, and a list that loads on
+ * its own through {@link usePagedList}, from its first page on.
  *
  * @module
  */

src/hooks/form/useApiForm.ts

@@ -1,5 +1,7 @@
 /**
- * react-hook-form, with the shared lifecycle of a form that posts to the API.
+ * Gives every form that posts to the API the same submit, which shows a failed
+ * request as the form's root error. It is react-hook-form's `useForm` plus that
+ * `submit`.
  *
  * @module
  */
@@ -15,7 +17,7 @@ import {
 
 import { friendlyFetchError } from "../../utils/shared/api.ts";
 
-/** What {@link useApiForm} returns: the form, and `submit`. */
+/** Returned by {@link useApiForm}, the form with `submit` added. */
 export interface UseApiFormResult<T extends FieldValues>
   extends UseFormReturn<T> {
   /**

src/hooks/playlist/usePlaylist.ts

@@ -1,6 +1,7 @@
 /**
- * Loads a playlist with its dumps for its page, keeps them live, and makes the
- * changes its owner or a moderator makes there.
+ * Everything a playlist's page shows and changes goes through this hook. It
+ * loads the playlist with its dumps, keeps them live, and makes the changes its
+ * owner or a moderator makes there.
  *
  * @module
  */

src/hooks/playlist/usePlaylistMemberships.ts

@@ -1,6 +1,7 @@
 /**
- * Loads which of the signed-in user's playlists hold a dump, and adds the dump
- * to them or takes it out.
+ * Lets the user add a dump to their playlists or take it out, in
+ * `AddToPlaylistModal` and the dump form's last step. It loads which of their
+ * playlists hold the dump.
  *
  * @module
  */

src/hooks/profile/useProfile.ts

@@ -1,6 +1,7 @@
 /**
- * Loads a profile's user with the first page of their dumps, upvotes and
- * playlists, and keeps them live.
+ * Everything a profile page shows comes through this hook. It loads the user
+ * with the first page of their dumps, upvotes and playlists, and keeps them
+ * live.
  *
  * @module
  */

src/hooks/shared/useFetchState.ts

@@ -1,5 +1,6 @@
 /**
- * Loads one thing from the API, once per key, when first asked to.
+ * Lets a component load one thing from the API the first time it's needed, and
+ * keep it for as long as its key holds, as the profile's lazy tabs do.
  *
  * @module
  */

src/hooks/social/useFollows.ts

@@ -1,5 +1,6 @@
 /**
- * Reads `FollowContext`, for the Follow buttons.
+ * Tells a Follow button what the user follows, and follows or unfollows, by
+ * reading `FollowContext`.
  *
  * @module
  */

src/hooks/ws/useWS.ts

@@ -1,7 +1,7 @@
 /**
- * Reads the live state that `WSProvider` keeps from the WebSocket. Each hook
- * reads one of its three contexts, so that a component re-renders only with
- * the part it uses. Outside `WSProvider`, they return inert defaults.
+ * Gives components the server's live updates. Each hook reads one of the three
+ * contexts `WSProvider` fills, so that a component re-renders only with the
+ * part it uses. Outside `WSProvider`, they return inert defaults.
  *
  * @module
  */