Add links to swr documentation

Author: htunnicliff

README.md

@@ -83,7 +83,11 @@ const prefix = "some-api";
 export const useQuery = createQueryHook(client, prefix);
 export const useImmutable = createImmutableHook(client, prefix);
 export const useInfinite = createInfiniteHook(client, prefix);
-export const useMutate = createMutateHook(client, prefix, _.isMatch);
+export const useMutate = createMutateHook(
+  client,
+  prefix,
+  _.isMatch, // Or any comparision function
+);
 ```
 
 ### Parameters
@@ -106,6 +110,8 @@ Each builder hook accepts the same initial parameters:
 
 ## `useQuery`
 
+This hook is a typed wrapper over [`useSWR`][swr-api].
+
 ```ts
 const useQuery = createQueryHook(/* ... */);
 
@@ -161,6 +167,8 @@ function useQuery(path, ...[init, config]) {
 
 ## `useImmutable`
 
+This hook has the same contracts as `useQuery`. However, instead of wrapping [`useSWR`][swr-api], it wraps `useSWRImmutable`. This immutable hook [disables automatic revalidations][swr-disable-auto-revalidate] but is otherwise identical to `useSWR`.
+
 ```ts
 const useImmutable = createImmutableHook(/* ... */);
 
@@ -171,8 +179,6 @@ const { data, error, isLoading, isValidating, mutate } = useImmutable(
 );
 ```
 
-This hook has the same contracts as `useQuery`. However, instead of wrapping [`useSWR`][swr-api], it wraps `useSWRImmutable`. This immutable hook [disables automatic revalidations][swr-disable-auto-revalidate] but is otherwise identical to `useSWR`.
-
 ### Parameters
 
 Identical to `useQuery` [parameters](#parameters-1).
@@ -183,6 +189,8 @@ Identical to `useQuery` [returns](#returns-1).
 
 ## `useInfinite`
 
+This hook is a typed wrapper over [`useSWRInfinite`][swr-infinite].
+
 ```ts
 const useInfinite = createInfiniteHook(/* ... */);
 
@@ -241,9 +249,10 @@ This function is similar to the [`getKey`][swr-infinite-options] parameter accep
   - `undefined` (if on the first page).
   - The fetched response for the last page retrieved.
 
-#### Should Return
+#### Returns
 
 - [Fetch options][oai-fetch-options] for the next page to load.
+- `null` if no more pages should be loaded.
 
 #### Examples
 
@@ -319,18 +328,18 @@ useInfinite("/something", (pageIndex, previousPageData) => {
 
 ## `useMutate`
 
-```ts
-const mutate = useMutate();
-
-await mutate([path, init], data, options);
-```
-
 `useMutate` is a wrapper around SWR's [global mutate][swr-global-mutate] function. It provides a type-safe mechanism for updating and revalidating SWR's client-side cache for specific endpoints.
 
 Like global mutate, this mutate wrapper accepts three parameters: `key`, `data`, and `options`. The latter two parameters are identical to those in _bound mutate_. `key` can be either a path alone, or a path with fetch options.
 
 The level of specificity used when defining the key will determine which cached requests are updated. If only a path is provided, any cached request using that path will be updated. If fetch options are included in the key, the [`compare`](#compare) function will determine if a cached request's fetch options match the key's fetch options.
 
+```ts
+const mutate = useMutate();
+
+await mutate([path, init], data, options);
+```
+
 <details>
 <summary>How <code>useMutate</code> works</summary>
 
@@ -468,6 +477,5 @@ useQuery("/path", {
 [swr-infinite-return]: https://swr.vercel.app/docs/pagination#return-values
 [swr-infinite-options]: https://swr.vercel.app/docs/pagination#parameters
 [swr-global-mutate]: https://swr.vercel.app/docs/mutation#global-mutate
-[swr-bound-mutate]: https://swr.vercel.app/docs/mutation#bound-mutate
 [swr-mutate-params]: https://swr.vercel.app/docs/mutation#parameters
 [lodash-is-match]: https://lodash.com/docs/4.17.15#isMatch

src/immutable.ts

@@ -2,7 +2,10 @@ import useSWRImmutable from "swr/immutable";
 import { configureBaseQueryHook } from "./query-base.js";
 
 /**
+ * Produces a typed wrapper for [`useSWRImmutable`](https://swr.vercel.app/docs/revalidation.en-US#disable-automatic-revalidations).
+ *
  * ```ts
+ * import createClient from "openapi-fetch";
  * const client = createClient();
  *
  * const useImmutable = createImmutableHook(client, "<unique-key>");

src/infinite.ts

@@ -9,7 +9,10 @@ import type { TypesForGetRequest } from "./types.js";
 import { useCallback, useDebugValue } from "react";
 
 /**
+ * Produces a typed wrapper for [`useSWRInfinite`](https://swr.vercel.app/docs/pagination#useswrinfinite).
+ *
  * ```ts
+ * import createClient from "openapi-fetch";
  * const client = createClient();
  *
  * const useInfinite = createInfiniteHook(client, "<unique-key>");

src/mutate.ts

@@ -10,7 +10,10 @@ import type { TypesForGetRequest } from "./types.js";
 export type CompareFn = (init: any, partialInit: any) => boolean;
 
 /**
+ * Produces a typed wrapper for [`useSWRConfig#mutate`](https://swr.vercel.app/docs/mutation).
+ *
  * ```ts
+ * import createClient from "openapi-fetch";
  * import { isMatch } from "lodash";
  *
  * const client = createClient();

src/query.ts

@@ -2,7 +2,11 @@ import useSWR from "swr";
 import { configureBaseQueryHook } from "./query-base.js";
 
 /**
+ * Produces a typed wrapper for [`useSWR`](https://swr.vercel.app/docs/api).
+ *
  * ```ts
+ * import createClient from "openapi-fetch";
+ *
  * const client = createClient();
  *
  * const useQuery = createQueryHook(client, "<unique-key>");

src/types.ts

@@ -13,6 +13,9 @@ type TryKey<T, K extends PropertyKey> = T extends { [Key in K]?: unknown }
   ? T[K]
   : undefined;
 
+/**
+ * Provides specific types used within a given request
+ */
 export type TypesForRequest<
   Paths extends {},
   Method extends Extract<HttpMethod, keyof Paths[keyof Paths]>,
@@ -40,6 +43,11 @@ export type TypesForRequest<
   SWRResponse: SWRResponse<Data, Error, SWRConfig>;
 };
 
+/**
+ * Provides specific types for GET requests
+ *
+ * Uses {@link TypesForRequest}
+ */
 export type TypesForGetRequest<
   Paths extends {},
   Path extends PathsWithMethod<Paths, Extract<"get", keyof Paths[keyof Paths]>>,