docs: add documentation for cache.batch method (#12990) #13048
Style Review Completed
The pull request has 16 style issues.
Duration: 714ms
PR URL: #13048
Review Comments: The AI has posted 16 inline comments with suggestions
Summary of changes:
The documentation has been updated to ensure consistency with the style guide, including changes to API reference headings to include parentheses, the use of active voice, and the imperative mood for headings in tutorial sections. Bold text is now reserved for UI elements and user roles. Internal file paths have been removed from code block titles where not relevant, and link texts have been updated to be action-oriented. Unordered lists are used for non-sequential items, and the number of items is no longer specified in lists or tables. Noun phrases are used for reference documentation headings. Syntax highlighting now consistently uses `javascript`, and blockquotes are correctly used for quotes, with references appearing as standard paragraphs.
Annotations
Check notice on line 943 in docs/source/api/cache/InMemoryCache.mdx
apollo-librarian / AI Style Review
docs/source/api/cache/InMemoryCache.mdx#L943
API reference headings for methods should include parentheses, consistent with the `useQuery()` example in the style guide.
```suggestion
## `batch()`
```
Check warning on line 962 in docs/source/api/cache/InMemoryCache.mdx
apollo-librarian / AI Style Review
docs/source/api/cache/InMemoryCache.mdx#L962
Avoid directional language like "below" and use active voice.
```suggestion
The `batch` method accepts an `options` object that supports the following fields:
```
Check notice on line 986 in docs/source/api/cache/InMemoryCache.mdx
apollo-librarian / AI Style Review
docs/source/api/cache/InMemoryCache.mdx#L986
Bold text is reserved for UI elements and user roles. It should not be used for emphasis or status labels.
```suggestion
Required. A function that performs cache operations. Receives the cache instance as its argument.
```
Check warning on line 1003 in docs/source/api/cache/InMemoryCache.mdx
apollo-librarian / AI Style Review
docs/source/api/cache/InMemoryCache.mdx#L1003
Use the active voice.
```suggestion
Controls how the cache handles optimistic data:
```
Check notice on line 1055 in docs/source/api/cache/InMemoryCache.mdx
apollo-librarian / AI Style Review
docs/source/api/cache/InMemoryCache.mdx#L1055
Avoid including internal file paths in code block titles unless the user is expected to edit that specific file.
```suggestion
```ts
```
Check notice on line 16 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L16
Update the link text and anchor to use the imperative mood, consistent with the recommended heading change and the style guide's preference for action-oriented language.
```suggestion
| [Batch cache operations](#batch-cache-operations) | `cache.batch` | Group multiple cache operations into a single transaction for better performance. |
```
Check notice on line 306 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L306
Use the imperative mood for headings in tutorial or how-to sections to be more direct and action-oriented.
```suggestion
### Batch cache operations
```
Check notice on line 308 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L308
Use the imperative mood to provide direct instructions and avoid the passive 'When you need to...' construction.
```suggestion
Use `cache.batch` to group multiple cache operations into a single transaction. This provides two key benefits:
```
Check warning on line 310 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L310
Use unordered lists for items that are not a sequential set of steps. Simplify the language by removing 'thereby'.
```suggestion
- **Performance**: Watchers (and React components) are notified only once after all operations complete, rather than after each individual operation.
```
Check warning on line 311 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L311
Use unordered lists for items that are not a sequential set of steps.
```suggestion
- **Control**: You gain fine-grained control over optimistic updates and can intercept watcher notifications.
```
Check notice on line 340 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L340
Use the imperative mood for headings to describe the user's action.
```suggestion
#### Handle optimistic updates
```
Check warning on line 383 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L383
Do not specify the number of items in a list or table, as this might change.
```suggestion
The `optimistic` option accepts the following values:
```
Check warning on line 391 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L391
Use noun phrases for reference documentation headings to maintain consistency with sibling headings like "Return values".
```suggestion
#### Watcher notifications
```
Check notice on line 395 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L395
Use `javascript` instead of `js` for syntax highlighting to align with style guide examples.
```suggestion
```javascript
```
Check notice on line 419 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L419
Use `javascript` instead of `js` for syntax highlighting to align with style guide examples.
```suggestion
```javascript
```
Check notice on line 434 in docs/source/caching/cache-interaction.mdx
apollo-librarian / AI Style Review
docs/source/caching/cache-interaction.mdx#L434
Blockquotes (`>`) are for quotes; use a standard paragraph for references. Remove 'full' for simplicity.
```suggestion
See the API reference for [`cache.batch`](../api/cache/InMemoryCache/#batch).
```