vincent/gerbeur
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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.

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
khannurien
2026-09-27 21:13:07 +00:00
parent d62e4a9883
commit b85a71d86e
18 changed files with 599 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
README.md
View File

@@ -158,23 +158,22 @@ place that fetches from other sites. Tests mirror the source one file per
module, so the tests of `services/chat-service.ts` are in
`test/services/chat-service.test.ts`.
The backend is documented for `deno doc`, the same way in every file. Each
module opens with a `/** … @module */` block saying what it is for. Every
export has a JSDoc comment, and so does every field of an exported interface; a
comment that describes a declaration is always `/** */`, and `//` is only for
notes on the code inside. Functions open with a verb ("Returns…", "Checks…"),
everything else with a noun phrase. Parameters are named in the prose, in
backticks. `{@link}` points at symbols the file already has in scope. A
function that can throw to its caller says so with `@throws`: for an
The backend and `shared/` are documented for `deno doc`, the same way in every
file. Each module opens with a `/** … @module */` block saying what it is for.
Every export has a JSDoc comment, and so does every field of an exported
interface; a comment that describes a declaration is always `/** */`, and `//`
is only for notes on the code inside. Functions open with a verb ("Returns…",
"Checks…"), everything else with a noun phrase. Parameters are named in the
prose, in backticks. `{@link}` points at symbols the file already has in scope.
A function that can throw to its caller says so with `@throws`: for an
`APIException`, the statuses and when. A router's JSDoc lists its endpoints, one
line each: method and path, who may call it, what it does. `deno task doc`
builds the HTML reference into `docs/` from every module of `api/` and
`shared/` but the tests. Its index page is the module doc of `mod.ts` at the
root, which introduces the repository's three parts and links every documented
module (`mod.test.ts` checks it), and the `docs` workflow publishes it on every
push to `main` that touches them. `deno task doc:lint` checks
the rules the linter can see; `shared/` is not documented yet, so it still
fails there.
builds the HTML reference into `docs/` from every module of `api/` and `shared/`
but the tests. Its index page is the module doc of `mod.ts` at the root, which
introduces the repository's three parts and links every documented module
(`mod.test.ts` checks it), and the `docs` workflow publishes it on every push to
`main` that touches them. `deno task doc:lint` checks the rules the linter can
see.
Each of the frontend's `components/`, `contexts/`, `hooks/` and `utils/` is
split into the same domain folders — `auth`, `category`, `chat`, `comment`,