📝 Clarify updateQueryData usage (#1679)

docs/rtk-query/api/created-api/cache-management-utils.mdx

@@ -31,7 +31,7 @@ interface PatchCollection {
 
 - **Parameters**
   - `endpointName`: a string matching an existing endpoint name
-  - `args`: a cache key, used to determine which cached dataset needs to be updated
+  - `args`: an argument matching that used for a previous query call, used to determine which cached dataset needs to be updated
   - `updateRecipe`: an Immer `produce` callback that can apply changes to the cached state
 
 #### Description
@@ -44,7 +44,10 @@ The thunk returns an object containing `{patches: Patch[], inversePatches: Patch
 
 This is typically used as the first step in implementing optimistic updates. The generated `inversePatches` can be used to revert the updates by calling `dispatch(patchQueryData(endpointName, args, inversePatches))`. Alternatively, the `undo` method can be called directly to achieve the same effect.
 
-#### Example
+Note that the first two arguments (`endpointName` and `args`) are used to determine which existing
+cache entry to update. If no existing cache entry is found, the `updateRecipe` callback will not run.
+
+#### Example 1
 
 ```ts no-transpile
 const patchCollection = dispatch(
@@ -54,6 +57,50 @@ const patchCollection = dispatch(
 )
 ```
 
+In the example above, `'getPosts'` is provided for the `endpointName`, and `undefined` is provided
+for `args`. This will match a query cache key of `'getPosts(undefined)'`.
+
+i.e. it will match a cache entry that may have been created via any of the following calls:
+
+```ts no-transpile
+api.endpoints.getPosts.useQuery()
+
+useGetPostsQuery()
+
+useGetPostsQuery(undefined, { ...options })
+
+dispatch(api.endpoints.getPosts.initiate())
+
+dispatch(api.endpoints.getPosts.initiate(undefined, { ...options }))
+```
+
+#### Example 2
+
+```ts no-transpile
+const patchCollection = dispatch(
+  api.util.updateQueryData('getPostById', 1, (draftPost) => {
+    draftPost.name = 'Lilly'
+  })
+)
+```
+
+In the example above, `'getPostById'` is provided for the `endpointName`, and `1` is provided
+for `args`. This will match a query cache key of `'getPostById(1)'`.
+
+i.e. it will match a cache entry that may have been created via any of the following calls:
+
+```ts no-transpile
+api.endpoints.getPostById.useQuery(1)
+
+useGetPostByIdQuery(1)
+
+useGetPostByIdQuery(1, { ...options })
+
+dispatch(api.endpoints.getPostById.initiate(1))
+
+dispatch(api.endpoints.getPostById.initiate(1, { ...options }))
+```
+
 ### `patchQueryData`
 
 #### Signature