Update API reference docs for links: part 2 - #12822
Style Review Completed
The pull request has 12 style issues.
Duration: 1130ms
PR URL: #12822
Review Comments: The AI has posted 12 inline comments with suggestions
Summary of changes:
The documentation has been updated to improve clarity, consistency, and grammatical accuracy. Changes include correcting capitalization, replacing 'may' with 'might' or 'can' for improved precision, and using 'Although' instead of 'While' for non-simultaneous clauses. Additionally, specific headings and text referencing `PersistedQueryLink` on pages about `RemoveTypenameFromVariablesLink` have been corrected. The active voice has been favored, and italics for emphasis have been removed. Furthermore, 'that' is now used for restrictive clauses instead of 'which', and 'preceding' is used instead of 'above' for document references.
Annotations
Check warning on line 85 in docs/source/api/link/apollo-link-remove-typename.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-remove-typename.mdx#L85
Sentences should begin with a capital letter.
```suggestion
Place <code>RemoveTypenameFromVariablesLink</code> before the split link to remove <code>__typename</code> from variables for all operations.
```
Check notice on line 112 in docs/source/api/link/apollo-link-remove-typename.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-remove-typename.mdx#L112
Use 'might' for potential occurrences instead of 'may'.
```suggestion
You might need to retain the <code>__typename</code> field from a query's response—for example, in the case of [JSON scalar](https://github.com/taion/graphql-type-json) input fields.
```
Check notice on line 114 in docs/source/api/link/apollo-link-remove-typename.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-remove-typename.mdx#L114
Use 'Although' instead of 'While' when the two clauses are not happening simultaneously.
```suggestion
Although the [GraphQL type validation spec](https://spec.graphql.org/October2021/#sec-Input-Objects.Type-Validation) disallows input fields that begin with two underscores (<code>__</code>), this restriction doesn't apply when the input field is a [JSON scalar](https://github.com/taion/graphql-type-json). (A JSON scalar type accepts raw JSON as input.) You can configure <code>RemoveTypenameFromVariablesLink</code> link to retain <code>__typename</code> for certain <code>JSON</code> scalars.
```
Check failure on line 204 in docs/source/api/link/apollo-link-remove-typename.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-remove-typename.mdx#L204
This heading incorrectly refers to <code>PersistedQueryLink</code> on a page about <code>RemoveTypenameFromVariablesLink</code>.
```suggestion
#### <code>RemoveTypenameFromVariablesLink</code> options
```
Check failure on line 206 in docs/source/api/link/apollo-link-remove-typename.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-remove-typename.mdx#L206
This text incorrectly refers to <code>PersistedQueryLink</code> on a page about <code>RemoveTypenameFromVariablesLink</code>.
```suggestion
The <code>RemoveTypenameFromVariablesLink</code> class takes a configuration object:
```
Check notice on line 29 in docs/source/api/link/apollo-link-retry.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-retry.mdx#L29
Use 'can' instead of 'may' to describe capability. The active voice ('receives' instead of 'is given') is also clearer.
```suggestion
Instead of the options object, you can pass a function for <code>delay</code> and/or <code>attempts</code> to implement custom strategies for each. In both cases the function receives the same arguments (<code>attempt</code>, <code>operation</code>, <code>error</code>).
```
Check warning on line 8 in docs/source/api/link/apollo-link-ws.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-ws.mdx#L8
The word 'we' should not be capitalized mid-sentence.
```suggestion
**We no longer recommend using <code>WebSocketLink</code> or the <code>subscriptions-transport-ws</code> library**, because the library is not actively maintained. To execute subscriptions, we instead recommend using the newer <code>graphql-ws</code> library with the accompanying [<code>GraphQLWsLink</code>](./apollo-link-subscriptions).
```
Check warning on line 10 in docs/source/api/link/apollo-link-ws.mdx
apollo-librarian / AI Style Review
docs/source/api/link/apollo-link-ws.mdx#L10
Do not use italics for emphasis.
```suggestion
Whichever library you use, make sure you use the same library in your server and any clients you support. For more information, see [Choosing a subscription library](../../data/subscriptions/#choosing-a-subscription-library).
```
Check warning on line 59 in docs/source/api/link/persisted-queries.mdx
apollo-librarian / AI Style Review
docs/source/api/link/persisted-queries.mdx#L59
Do not use italics for emphasis.
```suggestion
You can use either Apollo Server or Apollo Router Core for APQs. They don't need to be used together.
```
Check notice on line 212 in docs/source/api/link/persisted-queries.mdx
apollo-librarian / AI Style Review
docs/source/api/link/persisted-queries.mdx#L212
Use 'that' for restrictive clauses instead of 'which'.
```suggestion
- <code>disable</code>: a function that takes a [<code>PersistedQueryLink.DisableFunctionOptions</code>](#persistedquerylinkdisablefunctionoptions) object and returns a boolean to disable any future persisted queries for that session. This defaults to disabling on <code>PersistedQueryNotSupported</code> error.
```
Check notice on line 213 in docs/source/api/link/persisted-queries.mdx
apollo-librarian / AI Style Review
docs/source/api/link/persisted-queries.mdx#L213
Use 'that' for restrictive clauses instead of 'which'.
```suggestion
- <code>retry</code>: a function that takes a [<code>PersistedQueryLink.RetryFunctionOptions</code>](#persistedquerylinkretryfunctionoptions) object and returns a boolean to retry the request with the full query text included. This defaults to <code>true</code> on <code>PersistedQueryNotSupported</code> or <code>PersistedQueryNotFound</code> errors.
```
Check warning on line 303 in docs/source/api/link/persisted-queries.mdx
apollo-librarian / AI Style Review
docs/source/api/link/persisted-queries.mdx#L303
Use 'preceding' instead of 'above' to refer to previous content in the document.
```suggestion
If you use the preceding loader, you can pass <code>{ generateHash: ({ documentId }) => documentId }</code> to the <code>PersistedQueryLink</code> class.
```