From a89d2f9c1ae7bd855c6554c61d20a3dd3a0f4f2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= <clement.o2p@gmail.com>
Date: Wed, 13 Apr 2022 19:14:03 +0200
Subject: [PATCH] docs(api): apply use-async-data page structure to use-fetch
 (#4332)

---
 docs/content/3.api/1.composables/use-fetch.md | 79 ++++++++++++++-----
 1 file changed, 58 insertions(+), 21 deletions(-)

diff --git a/docs/content/3.api/1.composables/use-fetch.md b/docs/content/3.api/1.composables/use-fetch.md
index 886bd12dca..1fcb59ed00 100644
--- a/docs/content/3.api/1.composables/use-fetch.md
+++ b/docs/content/3.api/1.composables/use-fetch.md
@@ -1,33 +1,70 @@
 # `useFetch`
 
-```ts
-const {
-  data: Ref<DataT>,
-  pending: Ref<boolean>,
-  refresh: (force?: boolean) => Promise<void>,
-  error?: any
-} = useFetch(url: string, options?)
+This composable provides a convenient wrapper around [`useAsyncData`](/api/composables/use-async-data) and [`$fetch`](/api/utils/$fetch). It automatically generates a key based on URL and fetch options, as well as infers API response type.
+
+## Type
+
+```ts [Signature]
+function useFetch(
+  url: string,
+  options?: UseFetchOptions
+): Promise<DataT>
+
+type UseFetchOptions = {
+  method?: string,
+  params?: SearchParams,
+  headers?: {key: string, value: string}[],
+  baseURL?: string,
+  server?: boolean
+  lazy?: boolean
+  default?: () => DataT
+  transform?: (input: DataT) => DataT
+  pick?: string[]
+}
+
+type DataT = {
+  data: Ref<DataT>
+  pending: Ref<boolean>
+  refresh: () => Promise<void>
+  error: Ref<any>
+}
 ```
 
-Available options:
+## Params
 
-* `key`: Provide a custom key
-* Options from [ohmyfetch](https://github.com/unjs/ohmyfetch)
+* **Url**: The URL to fetch
+* **Options (from [ohmyfetch](https://github.com/unjs/ohmyfetch))**:
   * `method`: Request method
   * `params`: Query params
   * `headers`: Request headers
   * `baseURL`: Base URL for the request
-* Options from `useAsyncData`
-  * `lazy`
-  * `server`
-  * `default`
-  * `pick`
-  * `transform`
+* **Options (from `useAsyncData`)**:
+  * `lazy`: Whether to resolve the async function after loading the route, instead of blocking navigation (defaults to `false`).
+  * `server`: Whether to fetch the data on server-side (defaults to `true`).
+  * `default`: A factory function to set the default value of the data, before the async function resolves - particularly useful with the `lazy: true` option.
+  * `pick`: Only pick specified keys in this array from `handler` function result.
+  * `transform`: A function that can be used to alter `handler` function result after resolving.
 
-The object returned by `useFetch` has the same properties as that returned by `useAsyncData` ([see above](#useasyncdata)).
+## Return values
 
-::ReadMore{link="/guide/features/data-fetching"}
-::
+* **data**: the result of the asynchronous function that is passed in
+* **pending**: a boolean indicating whether the data is still being fetched
+* **refresh**: a function that can be used to refresh the data returned by the `handler` function
+* **error**: an error object if the data fetching failed
 
-::ReadMore{link="/api/composables/use-async-data"}
-::
+By default, Nuxt waits until a `refresh` is finished before it can be executed again. Passing `true` as parameter skips that wait.
+
+## Example
+
+```ts
+const { data, pending, error, refresh } = useFetch(
+  'https://api.nuxtjs.dev/mountains',
+  {
+    pick: ['title']
+  }
+)
+```
+
+:ReadMore{link="/guide/features/data-fetching"}
+
+:LinkExample{link="/examples/composables/use-fetch"}