Skip to content

Update api reference docs for links: part 1 - #12819

Merged
jerelmiller merged 53 commits into
release-4.0from
jerel/more-link-docs
Aug 5, 2025
Merged

Update api reference docs for links: part 1#12819
jerelmiller merged 53 commits into
release-4.0from
jerel/more-link-docs

Tweak sentence

6e272c1
Select commit
Loading
Failed to load commit list.
Apollo Librarian / AI Style Review succeeded Aug 5, 2025 in 1m 7s

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."

⚠️ This review and suggested changes are AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

Annotations

Check warning on line 3 in docs/source/api/link/apollo-link-client-awareness.mdx

See this annotation in the file changed.

@apollo-librarian 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

See this annotation in the file changed.

@apollo-librarian 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

See this annotation in the file changed.

@apollo-librarian 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

See this annotation in the file changed.

@apollo-librarian 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

See this annotation in the file changed.

@apollo-librarian 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

See this annotation in the file changed.

@apollo-librarian 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.
```