Add additional JSDoc comments to commonly used APIs for better API re…

…ference and in-editor documentation. (#12975)

Co-authored-by: Matt Brophy <matt@brophy.org>

packages/react-router/lib/router/utils.ts

@@ -116,8 +116,28 @@ export type Submission =
  * this as a private implementation detail in case they diverge in the future.
  */
 interface DataFunctionArgs<Context> {
+  /** A {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Fetch Request instance} which you can use to read headers (like cookies, and {@link https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams URLSearchParams} from the request. */
   request: Request;
+  /**
+   * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+   * @example
+   * // app/routes.ts
+   * route("teams/:teamId", "./team.tsx"),
+   *
+   * // app/team.tsx
+   * export function loader({
+   *   params,
+   * }: Route.LoaderArgs) {
+   *   params.teamId;
+   *   //        ^ string
+   * }
+   **/
   params: Params;
+  /**
+   * This is the context passed in to your server adapter's getLoadContext() function.
+   * It's a way to bridge the gap between the adapter's request/response API with your React Router app.
+   * It is only applicable if you are using a custom server adapter.
+   */
   context?: Context;
 }
 
@@ -166,18 +186,56 @@ export interface ActionFunction<Context = any> {
  * Arguments passed to shouldRevalidate function
  */
 export interface ShouldRevalidateFunctionArgs {
+  /** This is the url the navigation started from. You can compare it with `nextUrl` to decide if you need to revalidate this route's data. */
   currentUrl: URL;
+  /** These are the {@link https://reactrouter.com/start/framework/routing#dynamic-segments dynamic route params} from the URL that can be compared to the `nextParams` to decide if you need to reload or not. Perhaps you're using only a partial piece of the param for data loading, you don't need to revalidate if a superfluous part of the param changed. */
   currentParams: AgnosticDataRouteMatch["params"];
+  /** In the case of navigation, this the URL the user is requesting. Some revalidations are not navigation, so it will simply be the same as currentUrl. */
   nextUrl: URL;
+  /** In the case of navigation, these are the {@link https://reactrouter.com/start/framework/routing#dynamic-segments dynamic route params}  from the next location the user is requesting. Some revalidations are not navigation, so it will simply be the same as currentParams. */
   nextParams: AgnosticDataRouteMatch["params"];
+  /** The method (probably `"GET"` or `"POST"`) used in the form submission that triggered the revalidation. */
   formMethod?: Submission["formMethod"];
+  /** The form action (`<Form action="/somewhere">`) that triggered the revalidation. */
   formAction?: Submission["formAction"];
+  /** The form encType (`<Form encType="application/x-www-form-urlencoded">) used in the form submission that triggered the revalidation*/
   formEncType?: Submission["formEncType"];
+  /** The form submission data when the form's encType is `text/plain` */
   text?: Submission["text"];
+  /** The form submission data when the form's encType is `application/x-www-form-urlencoded` or `multipart/form-data` */
   formData?: Submission["formData"];
+  /** The form submission data when the form's encType is `application/json` */
   json?: Submission["json"];
+  /** The status code of the action response */
   actionStatus?: number;
+  /**
+   * When a submission causes the revalidation this will be the result of the action—either action data or an error if the action failed. It's common to include some information in the action result to instruct shouldRevalidate to revalidate or not.
+   *
+   * @example
+   * export async function action() {
+   *   await saveSomeStuff();
+   *   return { ok: true };
+   * }
+   *
+   * export function shouldRevalidate({
+   *   actionResult,
+   * }) {
+   *   if (actionResult?.ok) {
+   *     return false;
+   *   }
+   *   return true;
+   * }
+   */
   actionResult?: any;
+  /**
+   * By default, React Router doesn't call every loader all the time. There are reliable optimizations it can make by default. For example, only loaders with changing params are called. Consider navigating from the following URL to the one below it:
+   *
+   * /projects/123/tasks/abc
+   * /projects/123/tasks/def
+   * React Router will only call the loader for tasks/def because the param for projects/123 didn't change.
+   *
+   * It's safest to always return defaultShouldRevalidate after you've done your specific optimizations that return false, otherwise your UI might get out of sync with your data on the server.
+   */
   defaultShouldRevalidate: boolean;
 }
 
@@ -556,8 +614,13 @@ export function matchRoutesImpl<
 export interface UIMatch<Data = unknown, Handle = unknown> {
   id: string;
   pathname: string;
+  /**
+   * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the matched route.
+   **/
   params: AgnosticRouteMatch["params"];
+  /** The return value from the matched route's loader or clientLoader */
   data: Data;
+  /** The {@link https://reactrouter.com/start/framework/route-module#handle handle object} exported from the matched route module */
   handle: Handle;
 }
 

packages/react-router/lib/types/route-module.ts

@@ -51,10 +51,15 @@ type MetaMatches<T extends RouteInfo[]> =
     : Array<MetaMatch<RouteInfo> | undefined>;
 
 export type CreateMetaArgs<T extends RouteInfo> = {
+  /** This is the current router `Location` object. This is useful for generating tags for routes at specific paths or query parameters. */
   location: Location;
+  /** {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route. */
   params: T["params"];
+  /** The return value for this route's server loader function */
   data: T["loaderData"];
+  /** Thrown errors that trigger error boundaries will be passed to the meta function. This is useful for generating metadata for error pages. */
   error?: unknown;
+  /** An array of the current {@link https://api.reactrouter.com/v7/interfaces/react_router.UIMatch.html route matches}, including parent route matches. */
   matches: MetaMatches<[...T["parents"], T]>;
 };
 export type MetaDescriptors = MetaDescriptor[];
@@ -109,11 +114,52 @@ type _CreateActionData<ServerActionData, ClientActionData> = Awaited<
 >
 
 type ClientDataFunctionArgs<T extends RouteInfo> = {
+  /**
+   * A {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Fetch Request instance} which you can use to read the URL, the method, the "content-type" header, and the request body from the request.
+   *
+   * @note Because client data functions are called before a network request is made, the Request object does not include the headers which the browser automatically adds. React Router infers the "content-type" header from the enc-type of the form that performed the submission.
+   **/
   request: Request;
+  /**
+   * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+   * @example
+   * // app/routes.ts
+   * route("teams/:teamId", "./team.tsx"),
+   *
+   * // app/team.tsx
+   * export function clientLoader({
+   *   params,
+   * }: Route.ClientLoaderArgs) {
+   *   params.teamId;
+   *   //        ^ string
+   * }
+   **/
   params: T["params"];
 };
 
-type ServerDataFunctionArgs<T extends RouteInfo> = ClientDataFunctionArgs<T> & {
+type ServerDataFunctionArgs<T extends RouteInfo> = {
+  /** A {@link https://developer.mozilla.org/en-US/docs/Web/API/Request Fetch Request instance} which you can use to read the url, method, headers (such as cookies), and request body from the request. */
+  request: Request;
+  /**
+   * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+   * @example
+   * // app/routes.ts
+   * route("teams/:teamId", "./team.tsx"),
+   *
+   * // app/team.tsx
+   * export function loader({
+   *   params,
+   * }: Route.LoaderArgs) {
+   *   params.teamId;
+   *   //        ^ string
+   * }
+   **/
+  params: T["params"];
+  /**
+   * This is the context passed in to your server adapter's getLoadContext() function.
+   * It's a way to bridge the gap between the adapter's request/response API with your React Router app.
+   * It is only applicable if you are using a custom server adapter.
+   */
   context: AppLoadContext;
 };
 
@@ -122,6 +168,7 @@ export type CreateServerLoaderArgs<T extends RouteInfo> =
 
 export type CreateClientLoaderArgs<T extends RouteInfo> =
   ClientDataFunctionArgs<T> & {
+    /** This is an asynchronous function to get the data from the server loader for this route. On client-side navigations, this will make a {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API fetch} call to the React Router server loader. If you opt-into running your clientLoader on hydration, then this function will return the data that was already loaded on the server (via Promise.resolve). */
     serverLoader: () => Promise<ServerDataFrom<T["module"]["loader"]>>;
   };
 
@@ -130,6 +177,7 @@ export type CreateServerActionArgs<T extends RouteInfo> =
 
 export type CreateClientActionArgs<T extends RouteInfo> =
   ClientDataFunctionArgs<T> & {
+    /** This is an asynchronous function that makes the {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API fetch} call to the React Router server action for this route. */
     serverAction: () => Promise<ServerDataFrom<T["module"]["action"]>>;
   };
 
@@ -154,13 +202,44 @@ type Matches<T extends RouteInfo[]> =
     : Array<Match<RouteInfo> | undefined>;
 
 export type CreateComponentProps<T extends RouteInfo> = {
+  /**
+   * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+   * @example
+   * // app/routes.ts
+   * route("teams/:teamId", "./team.tsx"),
+   *
+   * // app/team.tsx
+   * export default function Component({
+   *   params,
+   * }: Route.ComponentProps) {
+   *   params.teamId;
+   *   //        ^ string
+   * }
+   **/
   params: T["params"];
+  /** The data returned from the `loader` or `clientLoader` */
   loaderData: T["loaderData"];
+  /** The data returned from the `action` or `clientAction` following an action submission. */
   actionData?: T["actionData"];
+  /** An array of the current {@link https://api.reactrouter.com/v7/interfaces/react_router.UIMatch.html route matches}, including parent route matches. */
   matches: Matches<[...T["parents"], T]>;
 };
 
 export type CreateErrorBoundaryProps<T extends RouteInfo> = {
+  /**
+   * {@link https://reactrouter.com/start/framework/routing#dynamic-segments Dynamic route params} for the current route.
+   * @example
+   * // app/routes.ts
+   * route("teams/:teamId", "./team.tsx"),
+   *
+   * // app/team.tsx
+   * export function ErrorBoundary({
+   *   params,
+   * }: Route.ErrorBoundaryProps) {
+   *   params.teamId;
+   *   //        ^ string
+   * }
+   **/
   params: T["params"];
   error: unknown;
   loaderData?: T["loaderData"];