Reorder cancellation content and improve wording

Author: markerikson

docs/api/createAsyncThunk.md

@@ -211,73 +211,6 @@ const onClick = () => {
 }
 ```
 
-## Examples
-
-Requesting a user by ID, with loading state, and only one request at a time:
-
-```js
-import { createAsyncThunk, createSlice, unwrapResult } from '@reduxjs/toolkit'
-import { userAPI } from './userAPI'
-
-const fetchUserById = createAsyncThunk(
-  'users/fetchByIdStatus',
-  async (userId, { getState }) => {
-    const { loading } = getState().users
-    if (loading !== 'idle') {
-      return
-    }
-    const response = await userAPI.fetchById(userId)
-    return response.data
-  }
-)
-
-const usersSlice = createSlice({
-  name: 'users',
-  initialState: {
-    entities: [],
-    loading: 'idle',
-    error: null
-  },
-  reducers: {},
-  extraReducers: {
-    [fetchUserById.pending]: (state, action) => {
-      if (state.loading === 'idle') {
-        state.loading = 'pending'
-      }
-    },
-    [fetchUserById.fulfilled]: (state, action) => {
-      if (state.loading === 'pending') {
-        state.loading = 'idle'
-        state.push(action.payload)
-      }
-    },
-    [fetchUserById.rejected]: (state, action) => {
-      if (state.loading === 'pending') {
-        state.loading = 'idle'
-        state.error = action.error
-      }
-    }
-  }
-})
-
-const UsersComponent = () => {
-  const { users, loading, error } = useSelector(state => state.users)
-  const dispatch = useDispatch()
-
-  const fetchOneUser = async userId => {
-    try {
-      const resultAction = dispatch(fetchUserById(userId))
-      const user = unwrapResult(resultAction)
-      showToast('success', `Fetched ${user.name}`)
-    } catch (err) {
-      showToast('error', `Fetch failed: ${err.message}`)
-    }
-  }
-
-  // render UI here
-}
-```
-
 ## Cancellation
 
 If you want to cancel your running thunk before it has finished, you can use the `abort` method of the promise returned by `dispatch(fetchUserById(userId))`.
@@ -287,19 +220,21 @@ A real-life example of that would look like this:
 ```ts
 function MyComponent(props: { userId: string }) {
   React.useEffect(() => {
+    // Dispatching the thunk returns a promise
     const promise = dispatch(fetchUserById(props.userId))
     return () => {
+      // `createAsyncThunk` attaches an `abort()` method to the promise
       promise.abort()
     }
   }, [props.userId])
 }
 ```
 
-After a thunk has been cancelled this way, it will dispatch (and return) a `thunkName/rejected` action with an `AbortError` on the `error` property. The thunk will not dispatch any further actions.
+After a thunk has been cancelled this way, it will dispatch (and return) a `"thunkName/rejected"` action with an `AbortError` on the `error` property. The thunk will not dispatch any further actions.
 
 Additionally, your `payloadCreator` can use the `AbortSignal` it is passed via `thunkApi.signal` to actually cancel a costly asynchronous action.
 
-The `fetch` api of modern browsers aleady comes with support for an `AbortSignal`:
+The `fetch` api of modern browsers already comes with support for an `AbortSignal`:
 
 ```ts
 const fetchUserById = createAsyncThunk(
@@ -313,9 +248,9 @@ const fetchUserById = createAsyncThunk(
 )
 ```
 
-But of course, you can also use it manually.
+### Checking Cancellation Status
 
-### using `signal.aborted`
+### Reading the Signal Value
 
 You can use the `signal.aborted` property to regularly check if the thunk has been aborted and in that case stop costly long-running work:
 
@@ -338,7 +273,9 @@ const readStream = createAsyncThunk('readStream', async (stream: ReadableStream,
 }
 ```
 
-### using `signal.addEventListener('abort', () => ...)`
+#### Listening for Abort Events
+
+You can also call `signal.addEventListener('abort', callback)` to have logic inside the thunk be notified when `promise.abort()` was called.
 
 ```ts
 const readStream = createAsyncThunk(
@@ -357,3 +294,70 @@ const readStream = createAsyncThunk(
     })
 )
 ```
+
+## Examples
+
+Requesting a user by ID, with loading state, and only one request at a time:
+
+```js
+import { createAsyncThunk, createSlice, unwrapResult } from '@reduxjs/toolkit'
+import { userAPI } from './userAPI'
+
+const fetchUserById = createAsyncThunk(
+  'users/fetchByIdStatus',
+  async (userId, { getState }) => {
+    const { loading } = getState().users
+    if (loading !== 'idle') {
+      return
+    }
+    const response = await userAPI.fetchById(userId)
+    return response.data
+  }
+)
+
+const usersSlice = createSlice({
+  name: 'users',
+  initialState: {
+    entities: [],
+    loading: 'idle',
+    error: null
+  },
+  reducers: {},
+  extraReducers: {
+    [fetchUserById.pending]: (state, action) => {
+      if (state.loading === 'idle') {
+        state.loading = 'pending'
+      }
+    },
+    [fetchUserById.fulfilled]: (state, action) => {
+      if (state.loading === 'pending') {
+        state.loading = 'idle'
+        state.push(action.payload)
+      }
+    },
+    [fetchUserById.rejected]: (state, action) => {
+      if (state.loading === 'pending') {
+        state.loading = 'idle'
+        state.error = action.error
+      }
+    }
+  }
+})
+
+const UsersComponent = () => {
+  const { users, loading, error } = useSelector(state => state.users)
+  const dispatch = useDispatch()
+
+  const fetchOneUser = async userId => {
+    try {
+      const resultAction = dispatch(fetchUserById(userId))
+      const user = unwrapResult(resultAction)
+      showToast('success', `Fetched ${user.name}`)
+    } catch (err) {
+      showToast('error', `Fetch failed: ${err.message}`)
+    }
+  }
+
+  // render UI here
+}
+```