Update api reference docs for links: part 1 - #12819
Style Review Completed
The pull request has 6 style issues.
Duration: 746ms
PR URL: #12819
Review Comments: The AI has posted 6 inline comments with suggestions
Summary of changes:
The documentation changes include: ensuring descriptions are full, SEO-optimized sentences; replacing unspecific phrases like "in various ways" with concrete options; consistently using the imperative for instructions to clarify configuration precedence; adopting "Apollo recommends" for a more authoritative tone; and framing alternatives conditionally instead of using unopinionated phrasing like "you can."
Annotations
Check warning on line 3 in docs/source/api/link/apollo-link-client-awareness.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-client-awareness.mdx#L3
The description should be a full sentence (or two) that describes the page's content and is optimized for SEO.
```suggestion
description: Learn how to use the ClientAwarenessLink to send client information with your GraphQL operations. See API options for configuration.
```
Check notice on line 13 in docs/source/api/link/apollo-link-client-awareness.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-client-awareness.mdx#L13
Avoid unopinionated statements like "in various ways." Be specific about what the options are.
```suggestion
You can configure client awareness in Apollo Client at the client, link, or request level.
```
Check notice on line 17 in docs/source/api/link/apollo-link-client-awareness.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-client-awareness.mdx#L17
Use the imperative for instructions. This phrasing is also clearer about the configuration precedence.
```suggestion
Configure client awareness when you initialize your <code>ApolloClient</code> instance with the <code>clientAwareness</code> and <code>enhancedClientAwareness</code> options. Options configured at the link level or in the request context take precedence over this client-level configuration.
```
Check notice on line 35 in docs/source/api/link/apollo-link-client-awareness.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-client-awareness.mdx#L35
Use the imperative for instructions. This phrasing is also clearer about the configuration precedence.
```suggestion
Configure client awareness when you initialize an <code>HttpLink</code> with the <code>clientAwareness</code> and <code>enhancedClientAwareness</code> options. These options take precedence over the <code>ApolloClient</code> constructor configuration and are overridden by the request context.
```
Check notice on line 37 in docs/source/api/link/apollo-link-subscriptions.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-subscriptions.mdx#L37
Use "Apollo recommends" for a more authoritative tone. The rephrased sentence is also simpler and easier to read.
```suggestion
For strategies on retrying failed connections, see the [<code>graphql-ws</code> recipes](https://the-guild.dev/graphql/ws/recipes). Apollo recommends this approach because it provides more detailed information about why the connection failed than retrying from the link chain or your components.
```
Check notice on line 39 in docs/source/api/link/apollo-link-subscriptions.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-subscriptions.mdx#L39
Avoid unopinionated phrasing like "you can." Frame alternatives conditionally to guide the user toward the right choice for their situation.
```suggestion
If you need to handle retries more generically within the link chain, use [<code>RetryLink</code>](./apollo-link-retry). This link resends the operation to the terminating link upon failure.
```