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>

src/components/social/FollowButton.tsx

@@ -1,21 +1,37 @@
+/**
+ * The follow buttons, for a user and for a playlist.
+ *
+ * @module
+ */
+
 import { t } from "@lingui/core/macro";
 import { Trans } from "@lingui/react/macro";
 import { useAuth } from "../../hooks/auth/useAuth.ts";
 import { useFollows } from "../../hooks/social/useFollows.ts";
 
-interface FollowUserButtonProps {
+/** The props of {@link FollowUserButton}. */
+export interface FollowUserButtonProps {
+  /** The user's id. */
   targetUserId: string;
+  /** The user's name, for the button's label. */
   targetUsername: string;
 }
 
-interface FollowPlaylistButtonProps {
+/** The props of {@link FollowPlaylistButton}. */
+export interface FollowPlaylistButtonProps {
+  /** The playlist's id. */
   targetPlaylistId: string;
+  /** Whether it is public; only a public playlist can be followed. */
   isPublic: boolean;
 }
 
+/**
+ * Renders the button that follows or unfollows a user; nothing when signed out
+ * or on one's own profile.
+ */
 export function FollowUserButton(
   { targetUserId, targetUsername }: FollowUserButtonProps,
-) {
+): React.JSX.Element | null {
   const { user } = useAuth();
   const { followedUserIds, followUser, unfollowUser, isLoaded } = useFollows();
 
@@ -39,9 +55,13 @@ export function FollowUserButton(
   );
 }
 
+/**
+ * Renders the button that follows or unfollows a playlist; nothing when signed
+ * out or for a private playlist.
+ */
 export function FollowPlaylistButton(
   { targetPlaylistId, isPublic }: FollowPlaylistButtonProps,
-) {
+): React.JSX.Element | null {
   const { user } = useAuth();
   const { followedPlaylistIds, followPlaylist, unfollowPlaylist, isLoaded } =
     useFollows();

src/components/social/LikeButton.tsx

@@ -1,20 +1,37 @@
+/**
+ * A comment's like button.
+ *
+ * @module
+ */
+
 import { useRef, useState } from "react";
 import { t } from "@lingui/core/macro";
 import { API_URL } from "../../config/api.ts";
 import { UserListPopover } from "./UserListPopover.tsx";
 
-interface LikeButtonProps {
+/** The props of {@link LikeButton}. */
+export interface LikeButtonProps {
+  /** The comment's id. */
   commentId: string;
+  /** Its like count. */
   count: number;
+  /** Whether the user likes it. */
   liked: boolean;
+  /** Whether it is disabled (signed out). */
   disabled?: boolean;
+  /** Likes the comment; `shownCount` is the count on screen. */
   onLike: (commentId: string, shownCount?: number) => void;
+  /** Withdraws the like; `shownCount` is the count on screen. */
   onUnlike: (commentId: string, shownCount?: number) => void;
 }
 
+/**
+ * Renders a comment's like button with its count, which opens the list of who
+ * likes it.
+ */
 export function LikeButton(
   { commentId, count, liked, disabled, onLike, onUnlike }: LikeButtonProps,
-) {
+): React.JSX.Element {
   const [popoverOpen, setPopoverOpen] = useState(false);
   const countRef = useRef<HTMLSpanElement>(null);
 

src/components/social/UserListPopover.tsx

@@ -1,3 +1,9 @@
+/**
+ * A popover listing users: who voted for a dump, who likes a comment.
+ *
+ * @module
+ */
+
 import { useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { Link } from "react-router";
@@ -11,12 +17,17 @@ import type { PaginatedData, Wire } from "../../../shared/api.ts";
 import { parseAPIResponse } from "../../utils/shared/api.ts";
 import type { PublicUser } from "../../../shared/user.ts";
 
-interface UserListPopoverProps {
+/** The props of {@link UserListPopover}. */
+export interface UserListPopoverProps {
+  /** The element it opens against. */
   anchorRef: React.RefObject<HTMLElement | null>;
+  /** Called to close it: an outside click, Escape, or a scroll. */
   onClose: () => void;
+  /** The paginated endpoint listing the users. */
   fetchUrl: string;
 }
 
+/** The list's state: loading, failed, or loaded with a page of users. */
 type State =
   | { status: "loading" }
   | { status: "error"; error: string }
@@ -28,6 +39,7 @@ type State =
     loadingMore: boolean;
   };
 
+/** Where the popover sits, in viewport coordinates. */
 interface Placement {
   left: number;
   top?: number;
@@ -35,13 +47,21 @@ interface Placement {
   maxHeight: number;
 }
 
+/** The popover's preferred largest height, in px. */
 const PREFERRED_MAX_HEIGHT = 280;
+/** The space kept clear of the viewport's edges, in px. */
 const VIEWPORT_MARGIN = 8;
+/** The least height worth opening below the anchor, in px. */
 const MIN_USABLE_HEIGHT = 100;
 
+/**
+ * Renders the users from `fetchUrl`, loading more on demand, in a popover
+ * against `anchorRef`. It is fixed and portaled to <body> so a card's overflow
+ * can't clip it, and flips above the anchor when there isn't enough room below.
+ */
 export function UserListPopover(
   { anchorRef, onClose, fetchUrl }: UserListPopoverProps,
-) {
+): React.ReactPortal | null {
   const { token } = useAuth();
   const [state, setState] = useState<State>({ status: "loading" });
   const [placement, setPlacement] = useState<Placement | null>(null);

src/components/social/VoteButton.tsx

@@ -1,20 +1,36 @@
+/**
+ * A dump's vote button.
+ *
+ * @module
+ */
+
 import { useRef, useState } from "react";
 import { t } from "@lingui/core/macro";
 import { API_URL } from "../../config/api.ts";
 import { UserListPopover } from "./UserListPopover.tsx";
 
-interface VoteButtonProps {
+/** The props of {@link VoteButton}. */
+export interface VoteButtonProps {
+  /** The dump's id. */
   dumpId: string;
+  /** Its vote count. */
   count: number;
+  /** Whether the user upvoted it. */
   voted: boolean;
+  /** Whether it is disabled (signed out). */
   disabled?: boolean;
+  /** Upvotes the dump; `shownCount` is the count on screen. */
   onCast: (dumpId: string, shownCount?: number) => void;
+  /** Withdraws the vote; `shownCount` is the count on screen. */
   onRemove: (dumpId: string, shownCount?: number) => void;
 }
 
+/**
+ * Renders a dump's vote button with its count, which opens the list of voters.
+ */
 export function VoteButton(
   { dumpId, count, voted, disabled, onCast, onRemove }: VoteButtonProps,
-) {
+): React.JSX.Element {
   const [popoverOpen, setPopoverOpen] = useState(false);
   const countRef = useRef<HTMLSpanElement>(null);