Misc get started tweaks and more robust useLazyQuery documentation - #12833
Style Review Completed
The pull request has 17 style issues.
Duration: 528ms
PR URL: #12833
Review Comments: The AI has posted 17 inline comments with suggestions
Summary of changes:
This pull request includes several changes to improve the clarity, readability, and tone of the documentation. Revisions were made to simplify complex sentences, remove jargon, and rephrase content to be more reader-centric and direct. Contractions were introduced to maintain an approachable tone, and imperative verbs were used for instructions. Additionally, formatting for UI elements was updated to use bold text for better visibility.
Annotations
Check notice on line 257 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L257
The original phrasing is passive. This change uses more encouraging language ('ideal'), a contraction ('doesn't'), and simplifies the final clause for better readability and a more approachable tone.
```suggestion
The [<code>useLazyQuery</code>](../api/react/useLazyQuery) hook is ideal for manually executing queries. Unlike <code>useQuery</code>, <code>useLazyQuery</code> doesn't immediately execute its associated query. Instead, it returns a function that you call to execute the query.
```
Check warning on line 282 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L282
The original sentence is long and uses jargon ('tuple'). This revision simplifies the sentence structure for clarity and removes the `dataState` property, which is not part of the returned object.
```suggestion
The <code>useLazyQuery</code> hook returns a tuple where the first item is the execution function. The second item is an object containing the query's result, with properties like <code>loading</code>, <code>error</code>, and <code>data</code>.
```
Check notice on line 286 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L286
This change reframes the sentence to be more reader-centric ('if you provide') and uses a contraction ('doesn't') to align with the approachable voice.
```suggestion
Unlike <code>useQuery</code>, if you provide options to <code>useLazyQuery</code> that change on re-renders, the hook doesn't automatically execute the query. Instead, <code>useLazyQuery</code> waits for you to call the execution function again before running the query with the updated options.
```
Check notice on line 309 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L309
This revision uses contractions ('isn't'), favors the present tense ('use' instead of 'will be used'), and simplifies the sentence structure for better flow and readability.
```suggestion
The changed options are immediately applied to the underlying <code>ObservableQuery</code> (accessible via the <code>observable</code> property), even though the query isn't executed. This means other APIs, such as <code>refetch</code>, use the updated options even before you call the execution function again.
```
Check warning on line 317 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L317
Button names and other interactive UI elements should be formatted with bold.
```suggestion
The following example gets a specific dog's photo when you click the **Get photo** button:
```
Check warning on line 339 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L339
The original sentence is repetitive and difficult to parse. This change simplifies the structure to make the requirement clearer.
```suggestion
When using TypeScript, if the query you provide to <code>useLazyQuery</code> has required variables, you must pass them in the <code>variables</code> option to the execution function. If you don't provide this options argument, or if the <code>variables</code> option is missing required variables, you'll see a TypeScript error.
```
Check notice on line 345 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L345
This phrasing is more direct and action-oriented, which is helpful for instructional content.
```suggestion
To change variables, call the execution function again with the new variables.
```
Check warning on line 347 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L347
Button names and other interactive UI elements should be formatted with bold.
```suggestion
The following example gets the selected dog's photo when you click the **Get photo** button.
```
Check notice on line 380 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L380
This revision is more reader-centric ('until you call') and avoids repeating the word 'called' for better readability.
```suggestion
The <code>variables</code> property is empty until you call the execution function for the first time. Use the <code>called</code> property from <code>useLazyQuery</code> to check if the execution function has run at least once.
```
Check notice on line 430 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L430
The original sentence ending is slightly awkward. This change splits the sentence and rephrases the second part for improved clarity and flow.
```suggestion
In cases where you don't need to keep your component in sync with query state, use <code>client.query()</code> directly. This approach avoids unnecessary re-renders for data your component doesn't use.
```
Check notice on line 479 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L479
Use contractions like 'isn't' to maintain an approachable tone.
```suggestion
Errors always cause the promise to reject. The <code>error</code> property isn't set when the promise resolves.
```
Check notice on line 485 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L485
This revision is more reader-centric ('You can access') than the imperative 'Read', which is more suitable for explanatory text.
```suggestion
The promise resolves with an object that includes the error and any partial data from the query. You can access the partial data from the <code>data</code> property and the error from the <code>error</code> property.
```
Check notice on line 499 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L499
This change simplifies the phrasing ('is instead set to' -> 'is') and uses a contraction ('isn't') for better readability.
```suggestion
<code>data</code> might be <code>undefined</code> instead of containing partial data. This typically happens when a [network error](./error-handling#network-errors) causes the query to fail, because the error isn't associated with GraphQL execution.
```
Check warning on line 519 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L519
This revision simplifies the phrasing ('in the event a...is raised' -> 'if a...occurs') and uses a direct, imperative instruction ('Check if...') instead of 'We recommend', which is more authoritative.
```suggestion
<code>data</code> might be <code>undefined</code> if a [network error](./error-handling#network-errors) occurs. Check if <code>data</code> is <code>undefined</code> before using it to prevent issues if an error occurs during query execution.
```
Check notice on line 525 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L525
The original phrasing is slightly weak ('might find this undesirable'). This revision is more direct and clearly states the default behavior and the possibility of changing it.
```suggestion
By default, in-flight queries from <code>useLazyQuery</code> are aborted when their component unmounts, which rejects the promise. If you need the query to run to completion, you can change this behavior.
```
Check notice on line 527 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L527
Using an imperative verb ('Call this method') is more direct and instructive for the reader.
```suggestion
The promise returned by the execution function includes a <code>.retain()</code> method. Call this method to ensure the query continues running even if the component unmounts.
```
Check notice on line 548 in docs/source/data/queries.mdx
apollo-librarian / AI Style Review
docs/source/data/queries.mdx#L548
This change makes the sentence more reader-centric ('you can shorten') and improves the logical flow by adding 'so'.
```suggestion
The <code>retain()</code> method returns the original promise, so you can shorten the previous example to a single line:
```