docs(api/hooks): add some extra reference links

Author: MichaelDeBoey

packages/react-router/lib/hooks.tsx

@@ -53,7 +53,7 @@ import {
 import type { SerializeFrom } from "./types/route-data";
 
 /**
- * Resolves a URL against the current location.
+ * Resolves a URL against the current {@link Location}.
  *
  * @example
  * import { useHref } from "react-router";
@@ -67,8 +67,8 @@ import type { SerializeFrom } from "./types/route-data";
  * @category Hooks
  * @param to The path to resolve
  * @param options Options
- * @param options.relative Defaults to "route" so routing is relative to the route tree.
- * Set to "path" to make relative routing operate against path segments.
+ * @param options.relative Defaults to `"route"` so routing is relative to the route tree.
+ * Set to `"path"` to make relative routing operate against path segments.
  * @returns The resolved href string
  */
 export function useHref(
@@ -100,14 +100,14 @@ export function useHref(
 }
 
 /**
- * Returns true if this component is a descendant of a Router, useful to ensure
+ * Returns `true` if this component is a descendant of a [`Router`](../declarative-routers/Router), useful to ensure
  * a component is used within a Router.
  *
  * @public
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns Whether the component is within a Router context
+ * @returns Whether the component is within a [`Router`](../declarative-routers/Router) context
  */
 export function useInRouterContext(): boolean {
   return React.useContext(LocationContext) != null;
@@ -149,26 +149,26 @@ export function useLocation(): Location {
 }
 
 /**
- * Returns the current navigation action which describes how the router came to
- * the current location, either by a pop, push, or replace on the history stack.
+ * Returns the current {@link Navigation} action which describes how the router came to
+ * the current {@link Location}, either by a pop, push, or replace on the [`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) stack.
  *
  * @public
  * @category Hooks
- * @returns The current navigation type (Action.Pop, Action.Push, or Action.Replace)
+ * @returns The current {@link Navigation} type ({@link Action.Pop}, {@link Action.Push}, or {@link Action.Replace})
  */
 export function useNavigationType(): NavigationType {
   return React.useContext(LocationContext).navigationType;
 }
 
 /**
- * Returns a PathMatch object if the given pattern matches the current URL.
+ * Returns a {@link PathMatch} object if the given pattern matches the current URL.
  * This is useful for components that need to know "active" state, e.g.
- * `<NavLink>`.
+ * {@link NavLink | `<NavLink>`}.
  *
  * @public
  * @category Hooks
- * @param pattern The pattern to match against the current location
- * @returns The path match object if the pattern matches, null otherwise
+ * @param pattern The pattern to match against the current {@link Location}
+ * @returns The path match object if the pattern matches, `null` otherwise
  */
 export function useMatch<
   ParamKey extends ParamParseKey<Path>,
@@ -219,16 +219,16 @@ function useIsomorphicLayoutEffect(
  *
  * It's often better to use {@link redirect} in [`action`](../../start/framework/route-module#action)/[`loader`](../../start/framework/route-module#loader) functions than this hook.
  *
- * The returned function signature is `navigate(to, options?)/navigate(delta)` where:
+ * The returned function signature is `navigate(to, options?)`/`navigate(delta)` where:
  *
- * * `to` can be a string path, a `To` object, or a number (delta)
+ * * `to` can be a string path, a {@link To} object, or a number (delta)
  * * `options` contains options for modifying the navigation
- *   * `flushSync`: Wrap the DOM updates in `ReactDom.flushSync`
+ *   * `flushSync`: Wrap the DOM updates in [`ReactDom.flushSync`](https://react.dev/reference/react-dom/flushSync)
  *   * `preventScrollReset`: Do not scroll back to the top of the page after navigation
- *   * `relative`: "route" or "path" to control relative routing logic
- *   * `replace`: Replace the current entry in the history stack
- *   * `state`: Optional history state to include with the new `Location`
- *   * `viewTransition`: Enable `document.startViewTransition` for this navigation
+ *   * `relative`: `"route"` or `"path"` to control relative routing logic
+ *   * `replace`: Replace the current entry in the [`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) stack
+ *   * `state`: Optional history state to include with the new {@link Location}
+ *   * `viewTransition`: Enable [`document.startViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) for this navigation
  *
  * @example
  * import { useNavigate } from "react-router";
@@ -250,7 +250,7 @@ function useIsomorphicLayoutEffect(
  * navigate("/some/route?search=param");
  * ```
  *
- * ### Navigate with a `To` object
+ * ### Navigate with a {@link To} object
  *
  * All properties are optional.
  *
@@ -273,17 +273,17 @@ function useIsomorphicLayoutEffect(
  * navigate(-1);
  *
  * // forward
- * // often used in a multi-step wizard workflows
+ * // often used in a multistep wizard workflows
  * navigate(1);
  * ```
  *
- * Be cautions with `navigate(number)`. If your application can load up to a route that has a button that tries to navigate forward/back, there may not be a history entry to go back or forward to, or it can go somewhere you don't expect (like a different domain).
+ * Be cautious with `navigate(number)`. If your application can load up to a route that has a button that tries to navigate forward/back, there may not be a `[`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) entry to go back or forward to, or it can go somewhere you don't expect (like a different domain).
  *
- * Only use this if you're sure they will have an entry in the history stack to navigate to.
+ * Only use this if you're sure they will have an entry in the [`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) stack to navigate to.
  *
  * ### Replace the current entry in the history stack
  *
- * This will remove the current entry in the history stack, replacing it with a new one, similar to a server side redirect.
+ * This will remove the current entry in the [`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) stack, replacing it with a new one, similar to a server side redirect.
  *
  * ```tsx
  * navigate("/some/route", { replace: true });
@@ -296,13 +296,13 @@ function useIsomorphicLayoutEffect(
  * <br/>
  * <br/>
  *
- * To prevent `<ScrollRestoration>` from resetting the scroll position, use the `preventScrollReset` option.
+ * To prevent {@link ScrollRestoration | `<ScrollRestoration>`} from resetting the scroll position, use the `preventScrollReset` option.
  *
  * ```tsx
  * navigate("?some-tab=1", { preventScrollReset: true });
  * ```
  *
- * For example, if you have a tab interface connected to search params in the middle of a page and you don't want it to scroll to the top when a tab is clicked.
+ * For example, if you have a tab interface connected to search params in the middle of a page, and you don't want it to scroll to the top when a tab is clicked.
  *
  * @public
  * @category Hooks
@@ -393,20 +393,20 @@ const OutletContext = React.createContext<unknown>(null);
  *
  * @public
  * @category Hooks
- * @returns The context value passed to the Outlet
+ * @returns The context value passed to the {@link Outlet} component
  */
 export function useOutletContext<Context = unknown>(): Context {
   return React.useContext(OutletContext) as Context;
 }
 
 /**
  * Returns the element for the child route at this level of the route
- * hierarchy. Used internally by `<Outlet>` to render child routes.
+ * hierarchy. Used internally by {@link Outlet | `<Outlet>`} to render child routes.
  *
  * @public
  * @category Hooks
  * @param context The context to pass to the outlet
- * @returns The child route element or null if no child routes match
+ * @returns The child route element or `null` if no child routes match
  */
 export function useOutlet(context?: unknown): React.ReactElement | null {
   let outlet = React.useContext(RouteContext).outlet;
@@ -419,7 +419,7 @@ export function useOutlet(context?: unknown): React.ReactElement | null {
 }
 
 /**
- * Returns an object of key/value pairs of the dynamic params from the current URL that were matched by the routes. Child routes inherit all params from their parent routes.
+ * Returns an object of key/value-pairs of the dynamic params from the current URL that were matched by the routes. Child routes inherit all params from their parent routes.
  *
  * Assuming a route pattern like `/posts/:postId` is matched by `/posts/123` then `params.postId` will be `"123"`.
  *
@@ -530,7 +530,7 @@ export function useParams<
 }
 
 /**
- * Resolves the pathname of the given `to` value against the current location. Similar to {@link useHref}, but returns a {@link Path} instead of a string.
+ * Resolves the pathname of the given `to` value against the current {@link Location}. Similar to {@link useHref}, but returns a {@link Path} instead of a string.
  *
  * @example
  * import { useResolvedPath } from "react-router";
@@ -547,9 +547,9 @@ export function useParams<
  * @category Hooks
  * @param to The path to resolve
  * @param options Options
- * @param options.relative Defaults to "route" so routing is relative to the route tree.
- *                         Set to "path" to make relative routing operate against path segments.
- * @returns The resolved `Path` object with pathname, search, and hash
+ * @param options.relative Defaults to `"route"` so routing is relative to the route tree.
+ *                         Set to `"path"` to make relative routing operate against path segments.
+ * @returns The resolved {@link Path} object with `pathname`, `search`, and `hash`
  */
 export function useResolvedPath(
   to: To,
@@ -576,7 +576,6 @@ export function useResolvedPath(
  * The return value of `useRoutes` is either a valid React element you can use to render the route tree, or `null` if nothing matched.
  *
  * @example
- * import * as React from "react";
  * import { useRoutes } from "react-router";
  *
  * function App() {
@@ -601,7 +600,7 @@ export function useResolvedPath(
  * @public
  * @category Hooks
  * @param routes An array of route objects that define the route hierarchy
- * @param locationArg An optional location object or pathname string to use instead of the current location
+ * @param locationArg An optional {@link Location} object or pathname string to use instead of the current {@link Location}
  * @returns A React element to render the matched route, or `null` if no routes matched
  */
 export function useRoutes(
@@ -1172,7 +1171,7 @@ export function useRouteId() {
 }
 
 /**
- * Returns the current navigation, defaulting to an "idle" navigation when no navigation is in progress. You can use this to render pending UI (like a global spinner) or read FormData from a form navigation.
+ * Returns the current {@link Navigation}, defaulting to an "idle" navigation when no navigation is in progress. You can use this to render pending UI (like a global spinner) or read [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) from a form navigation.
  *
  * @example
  * import { useNavigation } from "react-router";
@@ -1188,17 +1187,18 @@ export function useRouteId() {
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns The current navigation object
+ * @returns The current {@link Navigation} object
  */
 export function useNavigation(): Navigation {
   let state = useDataRouterState(DataRouterStateHook.UseNavigation);
   return state.navigation;
 }
 
 /**
- * Revalidate the data on the page for reasons outside of normal data mutations like window focus or polling on an interval.
+ * Revalidate the data on the page for reasons outside of normal data mutations like [`Window` focus](https://developer.mozilla.org/en-US/docs/Web/API/Window/focus_event) or polling on an interval.
  *
  * @example
+ * ```tsx
  * import { useRevalidator } from "react-router";
  *
  * function WindowFocusRevalidator() {
@@ -1214,8 +1214,9 @@ export function useNavigation(): Navigation {
  *     </div>
  *   );
  * }
+ * ```
  *
- * Note that page data is already revalidated automatically after actions. If you find yourself using this for normal CRUD operations on your data in response to user interactions, you're probably not taking advantage of the other APIs like {@link useFetcher}, {@link Form}, {@link useSubmit} that do this automatically.
+ * Note that page data is already revalidated automatically after [`action`](../../start/framework/route-module#action)s. If you find yourself using this for normal CRUD operations on your data in response to user interactions, you're probably not taking advantage of the other APIs like {@link useFetcher}, {@link Form}, {@link useSubmit} that do this automatically.
  *
  * @public
  * @category Hooks
@@ -1240,14 +1241,14 @@ export function useRevalidator(): {
 }
 
 /**
- * Returns the active route matches, useful for accessing loaderData for
+ * Returns the active route matches, useful for accessing `loaderData` for
  * parent/child routes or the route "handle" property
  *
  * @public
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns An array of UI matches for the current route hierarchy
+ * @returns An array of {@link UIMatch | UI matches} for the current route hierarchy
  */
 export function useMatches(): UIMatch[] {
   let { matches, loaderData } = useDataRouterState(
@@ -1280,7 +1281,7 @@ export function useMatches(): UIMatch[] {
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns The data returned from the route's loader function
+ * @returns The data returned from the route's [`loader`](../../start/framework/route-module#loader) or [`clientLoader`](../../start/framework/route-module#clientloader) function
  */
 export function useLoaderData<T = any>(): SerializeFrom<T> {
   let state = useDataRouterState(DataRouterStateHook.UseLoaderData);
@@ -1289,7 +1290,7 @@ export function useLoaderData<T = any>(): SerializeFrom<T> {
 }
 
 /**
- * Returns the loader data for a given route by route ID.
+ * Returns the [`loader`](../../start/framework/route-module#loader) data for a given route by route ID.
  *
  * Route IDs are created automatically. They are simply the path of the route file
  * relative to the app folder without the extension.
@@ -1308,15 +1309,15 @@ export function useLoaderData<T = any>(): SerializeFrom<T> {
  * }
  *
  * // You can also specify your own route ID's manually in your routes.ts file:
- * route("/", "containers/app.tsx", { id: "app" }})
+ * route("/", "containers/app.tsx", { id: "app" })
  * useRouteLoaderData("app");
  *
  * @public
  * @category Hooks
  * @mode framework
  * @mode data
  * @param routeId The ID of the route to return loader data from
- * @returns The data returned from the specified route's loader function, or undefined if not found
+ * @returns The data returned from the specified route's [`loader`](../../start/framework/route-module#loader) function, or `undefined` if not found
  */
 export function useRouteLoaderData<T = any>(
   routeId: string
@@ -1326,7 +1327,7 @@ export function useRouteLoaderData<T = any>(
 }
 
 /**
- * Returns the action data from the most recent POST navigation form submission or `undefined` if there hasn't been one.
+ * Returns the [`action`](../../start/framework/route-module#action) data from the most recent `POST` navigation form submission or `undefined` if there hasn't been one.
  *
  * @example
  * import { Form, useActionData } from "react-router";
@@ -1351,7 +1352,7 @@ export function useRouteLoaderData<T = any>(
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns The data returned from the route's action function, or undefined if no action has been called
+ * @returns The data returned from the route's [`action`](../../start/framework/route-module#action) function, or `undefined` if no `action` has been called
  */
 export function useActionData<T = any>(): SerializeFrom<T> | undefined {
   let state = useDataRouterState(DataRouterStateHook.UseActionData);
@@ -1378,7 +1379,7 @@ export function useActionData<T = any>(): SerializeFrom<T> | undefined {
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns The error that was thrown during route loading, action execution, or rendering
+ * @returns The error that was thrown during route [loading](../../start/framework/route-module#loader), [`action`](../../start/framework/route-module#action) execution, or rendering
  */
 export function useRouteError(): unknown {
   let error = React.useContext(RouteErrorContext);
@@ -1413,7 +1414,7 @@ export function useRouteError(): unknown {
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns The resolved value from the nearest Await component
+ * @returns The resolved value from the nearest {@link Await} component
  */
 export function useAsyncValue(): unknown {
   let value = React.useContext(AwaitContext);
@@ -1443,7 +1444,7 @@ export function useAsyncValue(): unknown {
  * @category Hooks
  * @mode framework
  * @mode data
- * @returns The error that was thrown in the nearest Await component
+ * @returns The error that was thrown in the nearest {@link Await} component
  */
 export function useAsyncError(): unknown {
   let value = React.useContext(AwaitContext);
@@ -1454,11 +1455,11 @@ let blockerId = 0;
 
 /**
  * Allow the application to block navigations within the SPA and present the
- * user a confirmation dialog to confirm the navigation.  Mostly used to avoid
- * using half-filled form data.  This does not handle hard-reloads or
+ * user a confirmation dialog to confirm the navigation. Mostly used to avoid
+ * using half-filled form data. This does not handle hard-reloads or
  * cross-origin navigations.
  *
- * The Blocker object returned by the hook has the following properties:
+ * The {@link Blocker} object returned by the hook has the following properties:
  *
  * - **`state`**
  *   - `unblocked` - the blocker is idle and has not prevented any navigation
@@ -1554,8 +1555,8 @@ let blockerId = 0;
  * @category Hooks
  * @mode framework
  * @mode data
- * @param shouldBlock Either a boolean or a function returning a boolean which indicates whether the navigation should be blocked.  The function format receives a single object parameter containing the `currentLocation`, `nextLocation`, and `historyAction` of the potential navigation.
- * @returns A blocker object with state and reset functionality
+ * @param shouldBlock Either a boolean or a function returning a boolean which indicates whether the navigation should be blocked. The function format receives a single object parameter containing the `currentLocation`, `nextLocation`, and `historyAction` of the potential navigation.
+ * @returns A {@link Blocker} object with state and reset functionality
  */
 export function useBlocker(shouldBlock: boolean | BlockerFunction): Blocker {
   let { router, basename } = useDataRouterContext(DataRouterHook.UseBlocker);

scripts/docs.ts

@@ -347,7 +347,9 @@ function generateMarkdownForComment(comment: SimplifiedComment): string {
   // Example section (if available)
   if (comment.example) {
     let example = resolveLinkTags(comment.example);
-    markdown += `\`\`\`tsx\n${example}\n\`\`\`\n\n`;
+    markdown += example.includes("```")
+      ? `${example}\n\n`
+      : `\`\`\`tsx\n${example}\n\`\`\`\n\n`;
   }
 
   // Signature section