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

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.

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
khannurien
2026-09-29 14:31:14 +00:00
parent 42e0356d21
commit 0d4e344d77
287 changed files with 5679 additions and 5135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
api/remote/providers/self.ts
View File

@@ -1,6 +1,7 @@
/**
* The link provider for this site's own pages, read from the database
* instead of fetched.
* Previews links to this site's own dump, user and playlist pages from the
* database, for `rich-content-service.ts`. No request goes out, so this works
* even when the site runs on a private host that `fetchWithTimeout` refuses.
*
* @module
*/
@@ -18,8 +19,8 @@ const USER_RE = /^\/users\/([^/]+)$/;
const PLAYLIST_RE = /^\/playlists\/([^/]+)$/;
/**
* Internal links carry gerbeur's own branding, so an art-less one still gets a
* recognizable placeholder instead of a generic tint.
* Gives a link to this site without a thumbnail a placeholder in the site's
* icon and color.
*/
const SELF_BRANDING = {
siteName: "gerbeur",
@@ -28,9 +29,9 @@ const SELF_BRANDING = {
} as const;
/**
* The provider for links to this site's dump, user and playlist pages, read
* from the database. Its `fetch` rejects with the services' `APIException` (404) for a
* page that doesn't exist or is private.
* Comes before the generic provider, and claims what `isSelfUrl` accepts. Its
* `fetch` rejects with the services' 404 `APIException` for a missing page or
* a private dump. A private playlist is previewed all the same.
*/
export const selfProvider: RichContentProvider = {
name: "self",
@@ -97,7 +98,7 @@ export const selfProvider: RichContentProvider = {
});
}
// Should not reach here if matches() is correct
// Unreachable: isSelfUrl accepts only the three paths above.
return Promise.resolve({ type: "generic", url });
},
};