add documentations for useSWRMutation (#348)

* reorganize the mutation page for useSWRMutation

* write paramters and return values sections for mutation

* docs: add examples of useSWRMutation

* add an exmple to use useSWRMutation for loading data

* Apply suggestions from code review

Co-authored-by: Jiachi Liu <inbox@huozhi.im>

Co-authored-by: Jiachi Liu <inbox@huozhi.im>

Author: koba04

pages/docs/mutation.en-US.md

@@ -1,16 +1,24 @@
 # Mutation
 
+SWR provides the `mutate` and `useSWRMutation` APIs for mutating remote data and related cache.
+
+## mutate
+
 ```js
 mutate(key, data, options)
 ```
 
-## Options
+### API
 
-- `optimisticData`: data to immediately update the client cache, or a function that receives current data and returns the new client cache data, usually used in optimistic UI.
-- `revalidate`: should the cache revalidate once the asynchronous update resolves.
-- `populateCache`: should the result of the remote mutation be written to the cache.
-- `populateCache`: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result.
-- `rollbackOnError`: should the cache rollback if the remote mutation errors.
+#### Parameters
+
+- `key`: same as `useSWR`'s `key`
+- `data`: data to update the client cache, or an async function for the remote mutation
+- `options`: accepts the following options
+  - `optimisticData(currentData)`: data to immediately update the client cache, or a function that receives current data and returns the new client cache data, usually used in optimistic UI.
+  - `revalidate = true`: should the cache revalidate once the asynchronous update resolves.
+  - `populateCache = true`: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result.
+  - `rollbackOnError = true`: should the cache rollback if the remote mutation errors.
 
 ## Revalidate
 
@@ -239,3 +247,121 @@ function Profile () {
   )
 }
 ```
+
+## useSWRMutation
+
+SWR also provides `useSWRMutation` as a hook for remote mutations. The remote mutations are only triggered manually, instead of automatically like `useSWR`.
+
+```jsx
+import useSWRMutation from 'swr/mutation'
+
+async function getData(url, { arg }) {
+  // Fetcher implementation.
+  // The extra argument will be passed via the `arg` property of the 2nd parameter.
+  // For the example below, `arg` will be `'my_token'`
+}
+
+// A useSWR + mutate like API, but it will never start the request.
+const { data, error, trigger, reset, isMutating } = useSWRMutation('/api/user', getData, options?)
+trigger('my_token');
+```
+
+### API
+
+#### Parameters
+
+- `key`:  same as `useSWR`'s `key`
+- `fetcher(key, { arg })`: an async function for remote mutation
+- `options`: accepts the following options
+  - `optimisticData(currentData)`: same as `mutate`'s `optimisticData`
+  - `revalidate = true`: same as `mutate`'s `revalidate`
+  - `populateCache = false`: same as `mutate`'s `populateCache`, but the default is `false`
+  - `rollbackOnError = true`: same as `mutate`'s `rollbackOnError`
+  - `onSuccess(data, key, config)`:　callback function when a remote mutation has been finished successfully
+  - `onError(err, key, config)`: callback function when a remote mutation has returned an error
+
+#### Return Values
+
+- `data`: data for the given key returned from `fetcher`
+- `error`: error thrown by `fetcher` (or undefined)
+- `trigger(arg, options)`: a function to trigger a remote mutation
+- `reset`: a function to reset the state (`data`, `error`, `isMutating`)
+- `isMutating`: if there's an ongoing remote mutation
+
+### Basic Examples
+
+```jsx
+import useSWRMutation from 'swr/mutation'
+
+async function sendRequest(url, { arg }) {
+  return fetch(url, {
+    method: 'POST',
+    body: JSON.stringify(arg)
+  })
+}
+
+function App() {
+  const { trigger } = useSWRMutation('/api/user', sendRequest, /* options */)
+
+  return (
+    <button
+      onClick={async () => {
+        try {
+          const result = await trigger({ username: 'johndoe' }, /* options */)
+        } catch (e) {
+          // error handling
+        }
+      }}
+    >
+      Create User
+    </button>
+  )
+}
+```
+
+If you want to use the mutation results in rendering, you can get them from the return values of `useSWRMutation`.
+
+```jsx
+const { trigger, data, error } = useSWRMutation('/api/user', sendRequest)
+```
+
+`useSWRMutation` shares a cache store with `useSWR`, so it can detect and avoid race conditions between `useSWR`. It also supports `mutate`'s functionalities like optimistic updates and rollback on errors. You can pass these options `useSWRMutation` and its `trigger` function.
+
+```jsx
+const { trigger } = useSWRMutation('/api/user', updateUser, {
+  optimisticData: current => ({ ...current, name: newName })
+})
+
+// or
+
+trigger(newName, {
+  optimisticData: current => ({ ...current, name: newName })
+})
+```
+
+### Defer loading data until needed
+
+You can also use `useSWRMutation` for loading data. `useSWRMutation` never start requesting until `trigger` is called, so you can defer loading data when you actually need it.
+
+```jsx
+import { useState } from 'react'
+import useSWRMutation from 'swr/mutation'
+
+const fetcher = url => fetch(url).then(res => res.json())
+
+const Page = () => {
+  const [show, setShow] = useState(false)
+  // data is undefined until trigger is called
+  const { data: user, trigger } = useSWR('/api/user', fetcher);
+
+  return (
+    <div>
+      <button onClick={() => {
+        trigger();
+        setShow(true);
+      }}>Show User</button>
+      {show && user ? <div>{usre.name}</div> : null}
+    </div>
+  );
+}
+```