Add JSDoc to public API (#5555)

* Add JSDoc comments to React Router hooks and components

Co-authored-by: tannerlinsley <[email protected]>

* Refactor: Rename "Non-obvious props/options" to "Props/Options"

Co-authored-by: tannerlinsley <[email protected]>

---------

Co-authored-by: Cursor Agent <[email protected]>

Author: tannerlinsley

packages/react-router/src/RouterProvider.tsx

@@ -7,6 +7,10 @@ import type {
   RouterOptions,
 } from '@tanstack/router-core'
 
+/**
+ * Low-level provider that places the router into React context and optionally
+ * updates router options from props. Most apps should use `RouterProvider`.
+ */
 export function RouterContextProvider<
   TRouter extends AnyRouter = RegisteredRouter,
   TDehydrated extends Record<string, any> = Record<string, any>,
@@ -44,6 +48,15 @@ export function RouterContextProvider<
   return provider
 }
 
+/**
+ * Top-level component that renders the active route matches and provides the
+ * router to the React tree via context.
+ *
+ * Accepts the same options as `createRouter` via props to update the router
+ * instance after creation.
+ *
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRouterFunction
+ */
 export function RouterProvider<
   TRouter extends AnyRouter = RegisteredRouter,
   TDehydrated extends Record<string, any> = Record<string, any>,

packages/react-router/src/link.tsx

@@ -539,7 +539,7 @@ export function createLink<const TComp>(
  * Handles path, search, hash and state updates with optional route preloading
  * and active-state styling.
  *
- * Non-obvious props include:
+ * Props:
  * - `preload`: Controls route preloading (eg. 'intent', 'render', 'viewport', true/false)
  * - `preloadDelay`: Delay in ms before preloading on hover
  * - `activeProps`/`inactiveProps`: Additional props merged when link is active/inactive

packages/react-router/src/useParams.tsx

@@ -61,6 +61,18 @@ export type UseParamsRoute<out TFrom> = <
     StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
 ) => UseParamsResult<TRouter, TFrom, true, TSelected>
 
+/**
+ * Access the current route's path parameters with type-safety.
+ *
+ * Options:
+ * - `from`/`strict`: Specify the matched route and whether to enforce strict typing
+ * - `select`: Project the params object to a derived value for memoized renders
+ * - `structuralSharing`: Enable structural sharing for stable references
+ * - `shouldThrow`: Throw if the route is not found in strict contexts
+ *
+ * @returns The params object (or selected value) for the matched route.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useParamsHook
+ */
 export function useParams<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,

packages/react-router/src/useRouter.tsx

@@ -3,6 +3,16 @@ import warning from 'tiny-warning'
 import { getRouterContext } from './routerContext'
 import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core'
 
+/**
+ * Access the current TanStack Router instance from React context.
+ * Must be used within a `RouterProvider`.
+ *
+ * Options:
+ * - `warn`: Log a warning if no router context is found (default: true).
+ *
+ * @returns The registered router instance.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useRouterHook
+ */
 export function useRouter<TRouter extends AnyRouter = RegisteredRouter>(opts?: {
   warn?: boolean
 }): TRouter {

packages/react-router/src/useRouterState.tsx

@@ -28,6 +28,18 @@ export type UseRouterStateResult<
   TSelected,
 > = unknown extends TSelected ? RouterState<TRouter['routeTree']> : TSelected
 
+/**
+ * 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
+ */
 export function useRouterState<
   TRouter extends AnyRouter = RegisteredRouter,
   TSelected = unknown,

packages/react-router/src/useSearch.tsx

@@ -61,6 +61,18 @@ export type UseSearchRoute<out TFrom> = <
     StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
 ) => UseSearchResult<TRouter, TFrom, true, TSelected>
 
+/**
+ * Read and select the current route's search parameters with type-safety.
+ *
+ * Options:
+ * - `from`/`strict`: Control which route's search is read and how strictly it's typed
+ * - `select`: Map the search object to a derived value for render optimization
+ * - `structuralSharing`: Enable structural sharing for stable references
+ * - `shouldThrow`: Throw when the route is not found (strict contexts)
+ *
+ * @returns The search object (or selected value) for the matched route.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useSearchHook
+ */
 export function useSearch<
   TRouter extends AnyRouter = RegisteredRouter,
   const TFrom extends string | undefined = undefined,