v3: the backend is documented for deno doc, one way in every file, and the docs build and publish themselves — comments were in three shapes: file headers as // lines, as an untagged /** */ (which deno doc drops, only an @module block counts) or missing; 43 exports described by a // deno doc can't see, two JSDoc blocks sitting on the wrong declaration and one duplicated; endpoints commented in 5 of 18 route files, three ways, on router.get() calls no doc tool reads. The rule, applied to every non-test module of api/, migrations included: each opens with a /** … @module */ block; every export has JSDoc, and so does every field of an exported interface; a comment describing a declaration is /** */, // only notes code; functions open with a verb, everything else with a noun phrase; parameters are named in the prose, {@link} only for symbols in scope; whatever throws to its caller says so with @throws (for an APIException, the statuses and when); a router's JSDoc lists its endpoints, method and path, who may call it, what it does. deno doc --lint goes from 528 errors to none in api/ (shared/ keeps its 385; it is next). The lint also wanted explicit types on config.ts's settings and a few return types, JsonLdResult exported, and the routers typed Router. deno task doc builds the HTML reference into docs/ from every module of api/ and shared/ but the tests, deno task doc:lint lints it; the index page is the module doc of a root mod.ts (deno.json's exports), which introduces the backend, shared/ and the frontend to come and links every module, and mod.test.ts fails when one is missing. The docs workflow builds it on every push to main that touches them and publishes it to the gh-pages branch, like publish-assistant's. Two defects found along the way are fixed: a private playlist's cover was served to anyone who had its id or slug, and now needs its owner's media token, as private dump files do (playlistImageUrl adds it for private playlists only, so public cover URLs stay the same for everyone); og.ts and static.ts each filled index.html's placeholders, and now share lib/index-html.ts, so the OG middleware picks up a rebuilt index.html instead of keeping the first it read. The README states the documentation rule. 205 backend and 628 frontend tests pass.

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

api/services/user-service.ts

@@ -1,3 +1,9 @@
+/**
+ * Users: accounts, profiles, lookups and search, and the invite tree.
+ *
+ * @module
+ */
+
 import { APIErrorCode } from "../../shared/api.ts";
 import { APIException } from "../lib/api-exception.ts";
 import type {
@@ -21,12 +27,19 @@ import { closeUserSockets, disconnectUser } from "./ws-service.ts";
 import { hashPassword } from "../lib/jwt.ts";
 import { linkAttachments } from "./attachment-service.ts";
 
+/** The query selecting full `UserRow`s from `users u`, with the inviter's name. */
 const USER_SELECT =
   `SELECT u.id, u.username, u.password_hash, u.role, u.created_at, u.updated_at, u.avatar_mime, u.description, u.invited_by, u.email,
           i.username as invited_by_username
    FROM users u
    LEFT JOIN users i ON i.id = u.invited_by`;
 
+/**
+ * Creates a user with the `user` role, invited by `inviterId`.
+ *
+ * @throws {APIException} 400 when the username is taken, 409 when the email
+ * is.
+ */
 export async function createUser(
   request: RegisterUserRequest,
   inviterId: string | null,
@@ -86,6 +99,11 @@ export async function createUser(
   };
 }
 
+/**
+ * Returns user `userId`.
+ *
+ * @throws {APIException} 404 when there is no such user.
+ */
 export function getUserById(userId: string): User {
   const userRow = db.prepare(
     `${USER_SELECT} WHERE u.id = ?`,
@@ -99,9 +117,9 @@ export function getUserById(userId: string): User {
 }
 
 /**
- * What a session token is checked against: the user's live role, and the
- * moment older tokens stopped counting (their last password change). Undefined
- * when the user is gone.
+ * Returns what a session token is checked against: the user's live role, and
+ * the moment older tokens stopped counting (their last password change).
+ * Undefined when the user is gone.
  */
 export function getSessionState(
   userId: string,
@@ -117,6 +135,11 @@ export function getSessionState(
   };
 }
 
+/**
+ * Returns the user named `username`.
+ *
+ * @throws {APIException} 404 when there is no such user.
+ */
 export function getUserByUsername(username: string): User {
   const userRow = db.prepare(
     `${USER_SELECT} WHERE u.username = ?`,
@@ -130,8 +153,9 @@ export function getUserByUsername(username: string): User {
 }
 
 /**
- * Password resets are looked up by email, so an address can belong to one
- * account only — otherwise which account a reset link resets is up to row order.
+ * Throws a 409 when another account than `exceptUserId` has `email`. Password
+ * resets are looked up by email, so an address can belong to one account only
+ * — otherwise which account a reset link resets is up to row order.
  */
 function assertEmailAvailable(email: string, exceptUserId?: string): void {
   const row = db.prepare(
@@ -146,6 +170,7 @@ function assertEmailAvailable(email: string, exceptUserId?: string): void {
   }
 }
 
+/** Returns the user whose email is `email`, or null. */
 export function getUserByEmail(email: string): User | null {
   const userRow = db.prepare(
     `${USER_SELECT} WHERE u.email = ?`,
@@ -155,6 +180,10 @@ export function getUserByEmail(email: string): User | null {
   return userRowToApi(userRow);
 }
 
+/**
+ * Returns up to `limit` users whose name starts with `query`, for @mention
+ * suggestions.
+ */
 export function searchUsers(
   query: string,
   limit: number,
@@ -174,7 +203,10 @@ export function searchUsers(
   }));
 }
 
-// For the public search page: profiles only, never hashes or emails.
+/**
+ * Returns up to `limit` users whose name or profile contains `query`, for the
+ * public search page: profiles only, never hashes or emails.
+ */
 export function searchUsersGlobal(query: string, limit: number): PublicUser[] {
   if (!query.trim()) return [];
   const pattern = `%${query}%`;
@@ -184,6 +216,7 @@ export function searchUsersGlobal(query: string, limit: number): PublicUser[] {
   return rows.filter(isUserRow).map(userRowToApi).map(toPublicUser);
 }
 
+/** Returns every user. */
 export function listUsers(): User[] {
   const userRows = db.prepare(
     `${USER_SELECT}`,
@@ -196,6 +229,13 @@ export function listUsers(): User[] {
   return userRows.map(userRowToApi);
 }
 
+/**
+ * Applies `request` to user `userId`. A new password also ends every session
+ * opened before it and closes the user's sockets.
+ *
+ * @throws {APIException} 404 when there is no such user, 409 when the new
+ * email belongs to another account.
+ */
 export async function updateUser(
   userId: string,
   request: UpdateUserRequest,
@@ -251,6 +291,11 @@ export async function updateUser(
   return updatedUser;
 }
 
+/**
+ * Records that user `userId` now has an avatar of type `mime`.
+ *
+ * @throws {APIException} 404 when there is no such user.
+ */
 export function updateUserAvatar(userId: string, mime: string): void {
   const result = db.prepare(
     `UPDATE users SET avatar_mime = ?, updated_at = ? WHERE id = ?`,
@@ -261,6 +306,10 @@ export function updateUserAvatar(userId: string, mime: string): void {
   }
 }
 
+/**
+ * Returns everyone `userId` invited, and everyone they invited in turn, down
+ * to ten levels, in registration order.
+ */
 export function getInviteTree(userId: string): Invitee[] {
   const rows = db.prepare(`
     WITH RECURSIVE tree AS (
@@ -291,6 +340,11 @@ export function getInviteTree(userId: string): Invitee[] {
   }));
 }
 
+/**
+ * Deletes user `userId` and disconnects their sockets.
+ *
+ * @throws {APIException} 404 when there is no such user.
+ */
 export function deleteUser(userId: string): void {
   disconnectUser(userId);