v3: src/ is documented like api/ and shared/, and the reference covers the whole repository — the frontend had no module docs, JSDoc on some components and hooks and not on others, props typed inline in half the components and in private interfaces in the rest, // comments on declarations, and no return types on 147 exported functions, so deno doc --lint over src/ found 637 errors. The rule api/ follows is applied to every non-test module of src/: a /** … @module */ block, JSDoc on every export and every field of an exported interface, /** */ for declarations and // for notes, verbs for functions ("Renders…" for a component), parameters named in the prose, {@link} only for symbols in scope, and a page's JSDoc names its route and who may see it (App.tsx's module doc lists the route table). For deno doc to show them, every exported function states its return type: components React.JSX.Element (or | null, or a portal), memo and forwardRef components their exotic types, contexts React.Context<…>, and a hook returning several things a documented Use<Name>Result interface (useAuth, useRequiredAuth, useFading, useEmojiTrigger, useMentionAutocomplete, useDumpCardLink, usePlayRichContent; FeedCacheResult, YouTubePlaylistControls and UseApiFormReturn are renamed to match). Every component that takes props takes an exported, documented <Name>Props interface — the 64 inline prop types are lifted into one, DumpFeed gets DumpFeedProps extending MainFeedProps. React types go through the global React namespace: the four default imports of react are gone, since deno doc can't follow them. Two duplicates go too: useMentionAutocomplete's UserResult was shared/'s UserSuggestion, and JournalCard re-exported JournalShape for no one; i18n.ts no longer re-exports Lingui's i18n, which its three users now import from @lingui/core. deno task doc and doc:lint now take src/ (but its tests and the generated locales), the index page gains a Frontend section linking every module by layer and domain, mod.test.ts walks src/ as well, and the docs workflow runs on changes to src/. deno doc doesn't document npm packages, so it takes a type imported from one — react-hook-form's FieldValues in the form fields, frimousse's SkinTone — for a private one; doc:lint now goes through doc-lint.ts, which fails on every diagnostic but those, 25 of them. The README states the frontend's part of the rule. No behaviour changes; 205 backend and 628 frontend tests pass, and tsc, deno check and deno lint are clean.

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

doc-lint.ts

@@ -0,0 +1,77 @@
+/**
+ * `deno task doc:lint`: runs `deno doc --lint` over the modules given as
+ * arguments and fails on what it reports, with one exception. `deno doc`
+ * doesn't document npm packages, so it calls every type imported from one
+ * private — react-hook-form's `FieldValues` in a form field's props, say —
+ * and no change to our own documentation could satisfy it. A `private-type-ref`
+ * whose type the module imports from a package is let through, and counted;
+ * every other diagnostic fails the run.
+ *
+ * @module
+ */
+
+/** One diagnostic of `deno doc --lint`. */
+interface Diagnostic {
+  /** The rule, e.g. `missing-jsdoc`. */
+  rule: string;
+  /** The rule's message. */
+  message: string;
+  /** The module it was reported in. */
+  file: string;
+  /** The diagnostic as printed, location and excerpt included. */
+  text: string;
+}
+
+/** Returns the diagnostics of `deno doc --lint` over `modules`. */
+async function lint(modules: string[]): Promise<Diagnostic[]> {
+  const { stderr } = await new Deno.Command(Deno.execPath(), {
+    args: ["doc", "--lint", ...modules],
+    env: { NO_COLOR: "1" },
+    stdout: "null",
+    stderr: "piped",
+  }).output();
+  const output = new TextDecoder().decode(stderr);
+  return output.split(/\n(?=error\[)/).flatMap((text) => {
+    const head = /^error\[([\w-]+)\]: (.*)$/m.exec(text);
+    const at = /--> (.+?):\d+:\d+/.exec(text);
+    if (!head || !at) return [];
+    return [{ rule: head[1], message: head[2], file: at[1], text }];
+  });
+}
+
+/** Checks whether module `file` imports `name` from a package. */
+function importedFromPackage(file: string, name: string): boolean {
+  const source = Deno.readTextFileSync(file);
+  const imports = source.matchAll(
+    /import\s+(?:type\s+)?([^;]*?)\s+from\s+"([^"]+)"/g,
+  );
+  for (const [, clause, specifier] of imports) {
+    if (specifier.startsWith(".")) continue;
+    const names = clause.replace(/[{}]/g, " ").split(",").map((part) =>
+      part.trim().replace(/^type\s+/, "").split(/\s+as\s+/).pop()!.trim()
+    );
+    if (names.includes(name)) return true;
+  }
+  return false;
+}
+
+/** Checks whether `d` is a private type from a package, which is let through. */
+function isPackageTypeRef(d: Diagnostic): boolean {
+  const type = /references private type '([\w$]+)/.exec(d.message)?.[1];
+  return d.rule === "private-type-ref" && !!type &&
+    importedFromPackage(d.file, type);
+}
+
+if (import.meta.main) {
+  const diagnostics = await lint(Deno.args);
+  const failures = diagnostics.filter((d) => !isPackageTypeRef(d));
+  for (const d of failures) console.error(d.text.trimEnd() + "\n");
+  const allowed = diagnostics.length - failures.length;
+  console.error(
+    `${failures.length} documentation lint errors` +
+      (allowed
+        ? `, ${allowed} references to npm packages' types let through`
+        : ""),
+  );
+  if (failures.length) Deno.exit(1);
+}