Add JSDoc to public API #5555
Merged
Add JSDoc to public API #5555
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: tannerlinsley <[email protected]>
|
Cursor Agent can help with this pull request. Just |
Contributor
WalkthroughDocumentation enhancements across React Router hooks through JSDoc additions and clarified comments. The useRouterState hook signature is updated with a new generic type parameter for structural sharing support, while preserving all existing runtime behavior. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Majority of changes are homogeneous documentation additions with consistent patterns. The type parameter addition to useRouterState is isolated to a single file with no apparent breaking changes to existing behavior. Suggested labels
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
|
View your CI Pipeline Execution ↗ for commit 27284ce
☁️ Nx Cloud last updated this comment at |
More templates
@tanstack/arktype-adapter
@tanstack/directive-functions-plugin
@tanstack/eslint-plugin-router
@tanstack/history
@tanstack/nitro-v2-vite-plugin
@tanstack/react-router
@tanstack/react-router-devtools
@tanstack/react-router-ssr-query
@tanstack/react-start
@tanstack/react-start-client
@tanstack/react-start-server
@tanstack/router-cli
@tanstack/router-core
@tanstack/router-devtools
@tanstack/router-devtools-core
@tanstack/router-generator
@tanstack/router-plugin
@tanstack/router-ssr-query-core
@tanstack/router-utils
@tanstack/router-vite-plugin
@tanstack/server-functions-plugin
@tanstack/solid-router
@tanstack/solid-router-devtools
@tanstack/solid-router-ssr-query
@tanstack/solid-start
@tanstack/solid-start-client
@tanstack/solid-start-server
@tanstack/start-client-core
@tanstack/start-plugin-core
@tanstack/start-server-core
@tanstack/start-static-server-functions
@tanstack/start-storage-context
@tanstack/valibot-adapter
@tanstack/virtual-file-routes
@tanstack/zod-adapter
commit: |
Co-authored-by: tannerlinsley <[email protected]>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/react-router/src/link.tsx (1)
542-549: Clarify that the list is non-exhaustive (was previously accurate).Changing the heading to “Props:” implies a complete list, but the bullets remain a subset (e.g., omits
disabled,replace,target,reloadDocument, etc.). Please either revert to a non-exhaustive label or expand/clarify.Suggested tweak:
- * Props: + * Key props (non‑exhaustive):Optionally, add a note about
disabledsemantics (removed for native , respected when rendering via_asChild).
🧹 Nitpick comments (6)
packages/react-router/src/RouterProvider.tsx (2)
10-13: Nice concise description. Consider annotating params for quick IntelliSense.Add brief
@paramentries forrouterand notable props (e.g.,context) and a one-liner about “props update router.options each render (shallow-merged)”. Improves clarity when hovering in editors.
51-59: Docs read well; a tiny usage example would help.Add a minimal snippet showing
<RouterProvider router={router} />with a comment that it should wrap the app root. Optional but practical.packages/react-router/src/useParams.tsx (1)
64-75: Solid overview. Add context and a tiny example for completeness.
- Add a note: “Must be used within a RouterProvider.”
- Optional: a one-liner example with
selectto show projection usage.Everything else looks good.
packages/react-router/src/useSearch.tsx (1)
64-75: Clear and consistent. Consider adding two small touches.
- Mention it must be used within a
RouterProvider.- Include a short
selectexample to show memoized projection.Nice work.
packages/react-router/src/useRouter.tsx (1)
6-15: Add optional example to JSDoc for better discoverability.The
@linkURL is correct and verified. Consider adding@example const router = useRouter()to the JSDoc block to help developers discover the hook's basic usage pattern.packages/react-router/src/useRouterState.tsx (1)
31-42: JSDoc improvements suggested; documentation URL verified but can be more specific.The JSDoc addition is helpful. To enhance IDE tooling and reader clarity:
- Add
@template,@param, and@returnstags for better type awareness- Document that
structuralSharingdefaults torouter.options.defaultStructuralSharing- Note that
selectshould be a stable function (e.g., viauseCallback) to avoid unnecessary recomputation- Update the docs link from
latesttov1for consistency with the current TanStack Router versioningSuggested edit:
-/** - * Subscribe to the router's state store with optional selection and - * structural sharing for render optimization. - * - * Options: - * - `select`: Project the full router state to a derived slice - * - `structuralSharing`: Replace-equal semantics for stable references - * - `router`: Read state from a specific router instance instead of context - * - * @returns The selected router state (or the full state by default). - * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterStateHook - */ +/** + * Subscribe to the router's state store with optional selection and + * structural sharing for render optimization. + * + * Options: + * - `select`: Project the full router state to a derived slice. Prefer a stable function (e.g. via `useCallback`). + * - `structuralSharing`: Replace-equal semantics for stable references. + * Defaults to `router.options.defaultStructuralSharing`. + * - `router`: Read state from a specific router instance instead of context. + * + * @template TRouter, TSelected, TStructuralSharing + * @param opts Options to customize selection, structural sharing, and router source. + * @returns The selected router state, or the full state when no selector is provided. + * @link https://tanstack.com/router/v1/docs/framework/react/api/router/useRouterStateHook + */
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
packages/react-router/src/RouterProvider.tsx(2 hunks)packages/react-router/src/link.tsx(1 hunks)packages/react-router/src/useParams.tsx(1 hunks)packages/react-router/src/useRouter.tsx(1 hunks)packages/react-router/src/useRouterState.tsx(1 hunks)packages/react-router/src/useSearch.tsx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use TypeScript in strict mode with extensive type safety across the codebase
Files:
packages/react-router/src/useRouter.tsxpackages/react-router/src/link.tsxpackages/react-router/src/RouterProvider.tsxpackages/react-router/src/useSearch.tsxpackages/react-router/src/useRouterState.tsxpackages/react-router/src/useParams.tsx
packages/{react-router,solid-router}/**
📄 CodeRabbit inference engine (AGENTS.md)
Implement React and Solid bindings/components only in packages/react-router/ and packages/solid-router/
Files:
packages/react-router/src/useRouter.tsxpackages/react-router/src/link.tsxpackages/react-router/src/RouterProvider.tsxpackages/react-router/src/useSearch.tsxpackages/react-router/src/useRouterState.tsxpackages/react-router/src/useParams.tsx
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add JSDoc annotations to core public APIs to improve self-documentation.
The task requested adding 5-10 concise JSDoc annotations to core, publicly documented APIs, prioritizing hooks and components, without altering existing JSDoc. This PR adds descriptions and parameter explanations to
useRouter,useSearch,useParams,useRouterState,RouterContextProvider, andRouterProvider.Summary by CodeRabbit
Documentation
New Features