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>
This commit is contained in:
khannurien
199
mod.ts
199
mod.ts
@@ -4,7 +4,7 @@
|
||||
* A small invite-only social platform for sharing links and files. The
|
||||
* repository holds three parts: the backend in `api/`, the frontend in `src/`,
|
||||
* and in `shared/` whatever crosses the wire between them. This reference
|
||||
* documents the backend and the shared modules; the frontend isn't in it yet.
|
||||
* documents all three.
|
||||
*
|
||||
* ## Backend — `api/`
|
||||
*
|
||||
@@ -155,7 +155,202 @@
|
||||
*
|
||||
* ## Frontend — `src/`
|
||||
*
|
||||
* The React app, built with Vite. Not in this reference yet.
|
||||
* The React app, built with Vite and translated with Lingui. Each layer holds
|
||||
* one kind of module, and every layer but pages/ is split into the same domains
|
||||
* (auth, category, chat, comment, dump, editor, feed, form, layout, player,
|
||||
* playlist, profile, social, theme, ws, and shared for what belongs to no one
|
||||
* domain). A page reads the API and the socket through contexts and hooks, and
|
||||
* draws with components; utils hold what isn't React at all.
|
||||
*
|
||||
* - **Entry point and app** — mounting, the providers and the route table, the
|
||||
* language: [App](./src/App.tsx/index.html),
|
||||
* [i18n](./src/i18n.ts/index.html), [main](./src/main.tsx/index.html).
|
||||
* - **Pages** — one component per route, each naming it, and the two guards
|
||||
* that wrap the routes for the signed in and the signed out:
|
||||
* [Dump](./src/pages/Dump.tsx/index.html),
|
||||
* [DumpEdit](./src/pages/DumpEdit.tsx/index.html),
|
||||
* [Index](./src/pages/Index.tsx/index.html),
|
||||
* [NotFound](./src/pages/NotFound.tsx/index.html),
|
||||
* [Notifications](./src/pages/Notifications.tsx/index.html),
|
||||
* [PlaylistDetail](./src/pages/PlaylistDetail.tsx/index.html),
|
||||
* [ResetPassword](./src/pages/ResetPassword.tsx/index.html),
|
||||
* [RestrictedGuest](./src/pages/RestrictedGuest.tsx/index.html),
|
||||
* [RestrictedLoggedIn](./src/pages/RestrictedLoggedIn.tsx/index.html),
|
||||
* [Search](./src/pages/Search.tsx/index.html),
|
||||
* [UserDumps](./src/pages/UserDumps.tsx/index.html),
|
||||
* [UserLogin](./src/pages/UserLogin.tsx/index.html),
|
||||
* [UserPlaylists](./src/pages/UserPlaylists.tsx/index.html),
|
||||
* [UserPublicProfile](./src/pages/UserPublicProfile.tsx/index.html),
|
||||
* [UserRegister](./src/pages/UserRegister.tsx/index.html),
|
||||
* [UserUpvoted](./src/pages/UserUpvoted.tsx/index.html).
|
||||
* - **Config** — settings read at startup:
|
||||
* [api](./src/config/api.ts/index.html),
|
||||
* [feedTabs](./src/config/feedTabs.ts/index.html),
|
||||
* [playerMode](./src/config/playerMode.ts/index.html).
|
||||
* - **Contexts** — a FooContext holding the state and its FooProvider, by
|
||||
* domain:
|
||||
* - auth: [AuthContext](./src/contexts/auth/AuthContext.ts/index.html),
|
||||
* [AuthProvider](./src/contexts/auth/AuthProvider.tsx/index.html).
|
||||
* - category:
|
||||
* [CategoriesContext](./src/contexts/category/CategoriesContext.ts/index.html),
|
||||
* [CategoriesProvider](./src/contexts/category/CategoriesProvider.tsx/index.html).
|
||||
* - chat: [ChatContext](./src/contexts/chat/ChatContext.ts/index.html),
|
||||
* [ChatProvider](./src/contexts/chat/ChatProvider.tsx/index.html).
|
||||
* - player:
|
||||
* [PlayerContext](./src/contexts/player/PlayerContext.ts/index.html),
|
||||
* [PlayerProvider](./src/contexts/player/PlayerProvider.tsx/index.html).
|
||||
* - social:
|
||||
* [FollowContext](./src/contexts/social/FollowContext.ts/index.html),
|
||||
* [FollowProvider](./src/contexts/social/FollowProvider.tsx/index.html).
|
||||
* - theme: [ThemeContext](./src/contexts/theme/ThemeContext.ts/index.html),
|
||||
* [ThemeProvider](./src/contexts/theme/ThemeProvider.tsx/index.html).
|
||||
* - ws:
|
||||
* [AvatarOverrideContext](./src/contexts/ws/AvatarOverrideContext.ts/index.html),
|
||||
* [WSContext](./src/contexts/ws/WSContext.ts/index.html),
|
||||
* [WSProvider](./src/contexts/ws/WSProvider.tsx/index.html).
|
||||
* - **Hooks** — every hook, by domain:
|
||||
* - auth: [useAuth](./src/hooks/auth/useAuth.ts/index.html).
|
||||
* - category:
|
||||
* [useCategories](./src/hooks/category/useCategories.ts/index.html).
|
||||
* - chat: [useChat](./src/hooks/chat/useChat.ts/index.html).
|
||||
* - dump: [useDumpCardLink](./src/hooks/dump/useDumpCardLink.ts/index.html),
|
||||
* [useDumpListSync](./src/hooks/dump/useDumpListSync.ts/index.html),
|
||||
* [useUserDumpFeed](./src/hooks/dump/useUserDumpFeed.ts/index.html).
|
||||
* - editor:
|
||||
* [useEmojiTrigger](./src/hooks/editor/useEmojiTrigger.ts/index.html),
|
||||
* [useMentionAutocomplete](./src/hooks/editor/useMentionAutocomplete.ts/index.html).
|
||||
* - feed:
|
||||
* [useDefaultFeedTab](./src/hooks/feed/useDefaultFeedTab.ts/index.html),
|
||||
* [useFading](./src/hooks/feed/useFading.ts/index.html),
|
||||
* [useFeedCache](./src/hooks/feed/useFeedCache.ts/index.html),
|
||||
* [useInfiniteScroll](./src/hooks/feed/useInfiniteScroll.ts/index.html),
|
||||
* [usePositionAwareSync](./src/hooks/feed/usePositionAwareSync.ts/index.html),
|
||||
* [useScrollSave](./src/hooks/feed/useScrollSave.ts/index.html).
|
||||
* - form: [useApiForm](./src/hooks/form/useApiForm.ts/index.html).
|
||||
* - player:
|
||||
* [usePlayRichContent](./src/hooks/player/usePlayRichContent.ts/index.html),
|
||||
* [useYouTubePlaylist](./src/hooks/player/useYouTubePlaylist.ts/index.html).
|
||||
* - playlist:
|
||||
* [usePlaylistListSync](./src/hooks/playlist/usePlaylistListSync.ts/index.html).
|
||||
* - shared:
|
||||
* [useAnchoredFloat](./src/hooks/shared/useAnchoredFloat.ts/index.html),
|
||||
* [useDocumentTitle](./src/hooks/shared/useDocumentTitle.ts/index.html),
|
||||
* [useHeightTransition](./src/hooks/shared/useHeightTransition.ts/index.html),
|
||||
* [useRoomBeside](./src/hooks/shared/useRoomBeside.ts/index.html),
|
||||
* [useScrollLock](./src/hooks/shared/useScrollLock.ts/index.html),
|
||||
* [useSoundsEnabled](./src/hooks/shared/useSoundsEnabled.ts/index.html),
|
||||
* [useTabParam](./src/hooks/shared/useTabParam.ts/index.html).
|
||||
* - social: [useFollows](./src/hooks/social/useFollows.ts/index.html).
|
||||
* - theme: [useTheme](./src/hooks/theme/useTheme.ts/index.html).
|
||||
* - ws: [useWS](./src/hooks/ws/useWS.ts/index.html).
|
||||
* - **Components** — only components, by domain:
|
||||
* - category:
|
||||
* [CategoryManager](./src/components/category/CategoryManager.tsx/index.html),
|
||||
* [CategorySelect](./src/components/category/CategorySelect.tsx/index.html),
|
||||
* [CategorySwitcher](./src/components/category/CategorySwitcher.tsx/index.html).
|
||||
* - chat: [ChatEditBox](./src/components/chat/ChatEditBox.tsx/index.html),
|
||||
* [ChatMessageItem](./src/components/chat/ChatMessageItem.tsx/index.html),
|
||||
* [ChatModal](./src/components/chat/ChatModal.tsx/index.html),
|
||||
* [PendingItem](./src/components/chat/PendingItem.tsx/index.html),
|
||||
* [ReplyRef](./src/components/chat/ReplyRef.tsx/index.html).
|
||||
* - comment:
|
||||
* [CommentForm](./src/components/comment/CommentForm.tsx/index.html),
|
||||
* [CommentNode](./src/components/comment/CommentNode.tsx/index.html),
|
||||
* [CommentThread](./src/components/comment/CommentThread.tsx/index.html).
|
||||
* - dump: [DumpCard](./src/components/dump/DumpCard.tsx/index.html),
|
||||
* [FilePreview](./src/components/dump/FilePreview.tsx/index.html),
|
||||
* [JournalCard](./src/components/dump/JournalCard.tsx/index.html),
|
||||
* [RichContentCard](./src/components/dump/RichContentCard.tsx/index.html),
|
||||
* [DumpCreateModal](./src/components/dump/create/DumpCreateModal.tsx/index.html),
|
||||
* [DuplicateNotice](./src/components/dump/create/DuplicateNotice.tsx/index.html),
|
||||
* [LocalFilePreview](./src/components/dump/create/LocalFilePreview.tsx/index.html),
|
||||
* [StepIndicator](./src/components/dump/create/StepIndicator.tsx/index.html),
|
||||
* [TitleField](./src/components/dump/create/TitleField.tsx/index.html).
|
||||
* - editor:
|
||||
* [EmojiPickerPopup](./src/components/editor/EmojiPickerPopup.tsx/index.html),
|
||||
* [Markdown](./src/components/editor/Markdown.tsx/index.html),
|
||||
* [MentionDropdown](./src/components/editor/MentionDropdown.tsx/index.html),
|
||||
* [TextEditor](./src/components/editor/TextEditor.tsx/index.html).
|
||||
* - feed: [DumpFeed](./src/components/feed/DumpFeed.tsx/index.html),
|
||||
* [FeedTabBar](./src/components/feed/FeedTabBar.tsx/index.html),
|
||||
* [FollowedFeed](./src/components/feed/FollowedFeed.tsx/index.html),
|
||||
* [JournalFeed](./src/components/feed/JournalFeed.tsx/index.html),
|
||||
* [PresenceRow](./src/components/feed/PresenceRow.tsx/index.html).
|
||||
* - form: [FileDropZone](./src/components/form/FileDropZone.tsx/index.html),
|
||||
* [FileField](./src/components/form/FileField.tsx/index.html),
|
||||
* [FormActions](./src/components/form/FormActions.tsx/index.html),
|
||||
* [FormError](./src/components/form/FormError.tsx/index.html),
|
||||
* [RichTextField](./src/components/form/RichTextField.tsx/index.html),
|
||||
* [SegmentedField](./src/components/form/SegmentedField.tsx/index.html),
|
||||
* [SubmitButton](./src/components/form/SubmitButton.tsx/index.html),
|
||||
* [TextField](./src/components/form/TextField.tsx/index.html).
|
||||
* - layout: [AppHeader](./src/components/layout/AppHeader.tsx/index.html),
|
||||
* [ChatButton](./src/components/layout/ChatButton.tsx/index.html),
|
||||
* [ChatFab](./src/components/layout/ChatFab.tsx/index.html),
|
||||
* [DumpFab](./src/components/layout/DumpFab.tsx/index.html),
|
||||
* [NotificationBell](./src/components/layout/NotificationBell.tsx/index.html),
|
||||
* [PageError](./src/components/layout/PageError.tsx/index.html),
|
||||
* [PageShell](./src/components/layout/PageShell.tsx/index.html),
|
||||
* [SearchBar](./src/components/layout/SearchBar.tsx/index.html),
|
||||
* [UserMenu](./src/components/layout/UserMenu.tsx/index.html).
|
||||
* - player:
|
||||
* [GlobalPlayer](./src/components/player/GlobalPlayer.tsx/index.html),
|
||||
* [MediaPlayer](./src/components/player/MediaPlayer.tsx/index.html),
|
||||
* [PlayerIcons](./src/components/player/PlayerIcons.tsx/index.html),
|
||||
* [SeekBar](./src/components/player/SeekBar.tsx/index.html),
|
||||
* [Waveform](./src/components/player/Waveform.tsx/index.html).
|
||||
* - playlist:
|
||||
* [AddToPlaylistModal](./src/components/playlist/AddToPlaylistModal.tsx/index.html),
|
||||
* [NewPlaylistButton](./src/components/playlist/NewPlaylistButton.tsx/index.html),
|
||||
* [PlaylistCard](./src/components/playlist/PlaylistCard.tsx/index.html),
|
||||
* [PlaylistCreateForm](./src/components/playlist/PlaylistCreateForm.tsx/index.html),
|
||||
* [PlaylistMembershipPanel](./src/components/playlist/PlaylistMembershipPanel.tsx/index.html).
|
||||
* - profile:
|
||||
* [ChangePasswordModal](./src/components/profile/ChangePasswordModal.tsx/index.html),
|
||||
* [ProfileSubpageHeader](./src/components/profile/ProfileSubpageHeader.tsx/index.html).
|
||||
* - shared: [Avatar](./src/components/shared/Avatar.tsx/index.html),
|
||||
* [ConfirmModal](./src/components/shared/ConfirmModal.tsx/index.html),
|
||||
* [CountedInput](./src/components/shared/CountedInput.tsx/index.html),
|
||||
* [ErrorCard](./src/components/shared/ErrorCard.tsx/index.html),
|
||||
* [ImagePicker](./src/components/shared/ImagePicker.tsx/index.html),
|
||||
* [Modal](./src/components/shared/Modal.tsx/index.html),
|
||||
* [TabBar](./src/components/shared/TabBar.tsx/index.html),
|
||||
* [Thumbnail](./src/components/shared/Thumbnail.tsx/index.html),
|
||||
* [ThumbnailPlaceholder](./src/components/shared/ThumbnailPlaceholder.tsx/index.html),
|
||||
* [Tooltip](./src/components/shared/Tooltip.tsx/index.html).
|
||||
* - social:
|
||||
* [FollowButton](./src/components/social/FollowButton.tsx/index.html),
|
||||
* [LikeButton](./src/components/social/LikeButton.tsx/index.html),
|
||||
* [UserListPopover](./src/components/social/UserListPopover.tsx/index.html),
|
||||
* [VoteButton](./src/components/social/VoteButton.tsx/index.html).
|
||||
* - **Utils** — every module that isn't React, by domain:
|
||||
* - auth: [permissions](./src/utils/auth/permissions.ts/index.html),
|
||||
* [storage](./src/utils/auth/storage.ts/index.html).
|
||||
* - chat: [draft](./src/utils/chat/draft.ts/index.html),
|
||||
* [message](./src/utils/chat/message.ts/index.html),
|
||||
* [text](./src/utils/chat/text.ts/index.html),
|
||||
* [time](./src/utils/chat/time.ts/index.html).
|
||||
* - dump: [draft](./src/utils/dump/draft.ts/index.html).
|
||||
* - editor: [skinTone](./src/utils/editor/skinTone.ts/index.html),
|
||||
* [text](./src/utils/editor/text.ts/index.html).
|
||||
* - feed: [hotScore](./src/utils/feed/hotScore.ts/index.html),
|
||||
* [journalLayout](./src/utils/feed/journalLayout.ts/index.html).
|
||||
* - player: [bandcamp](./src/utils/player/bandcamp.ts/index.html),
|
||||
* [duration](./src/utils/player/duration.ts/index.html),
|
||||
* [streamSources](./src/utils/player/streamSources.ts/index.html),
|
||||
* [volume](./src/utils/player/volume.ts/index.html),
|
||||
* [waveform](./src/utils/player/waveform.ts/index.html),
|
||||
* [youtube](./src/utils/player/youtube.ts/index.html).
|
||||
* - shared: [api](./src/utils/shared/api.ts/index.html),
|
||||
* [charCount](./src/utils/shared/charCount.ts/index.html),
|
||||
* [deserialize](./src/utils/shared/deserialize.ts/index.html),
|
||||
* [format](./src/utils/shared/format.ts/index.html),
|
||||
* [proxyImage](./src/utils/shared/proxyImage.ts/index.html),
|
||||
* [relativeTime](./src/utils/shared/relativeTime.ts/index.html),
|
||||
* [sound](./src/utils/shared/sound.ts/index.html),
|
||||
* [thumbnailTint](./src/utils/shared/thumbnailTint.ts/index.html),
|
||||
* [urls](./src/utils/shared/urls.ts/index.html),
|
||||
* [visited](./src/utils/shared/visited.ts/index.html).
|
||||
*
|
||||
* @module
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user