fix(hydrogen): remove wrong JSDoc @param/@returns on HydrogenCart delivery-address fields#3719
Open
andromia3 wants to merge 1 commit intoShopify:mainfrom
Open
fix(hydrogen): remove wrong JSDoc @param/@returns on HydrogenCart delivery-address fields#3719andromia3 wants to merge 1 commit intoShopify:mainfrom
andromia3 wants to merge 1 commit intoShopify:mainfrom
Conversation
…ivery-address fields
The four delivery-address fields on HydrogenCart
(addDeliveryAddresses, removeDeliveryAddresses, updateDeliveryAddresses,
replaceDeliveryAddresses) had JSDoc blocks copy-pasted from the factory
functions in `packages/hydrogen/src/cart/queries/cartDeliveryAddresses*`.
The factory functions take `(options: CartQueryOptions)` and return the
invokable method, but the fields on HydrogenCart are the already-built
methods — they take `(addresses, optionalParams?)` and return
`Promise<CartQueryDataReturn>`. So every `@param {CartQueryOptions} options`
and `@returns {...Function}` tag on these fields was describing the wrong
function, and that wrong text surfaces in IDE hovers and in the
Shopify.dev reference docs generated from this file.
Removed the four wrong `@param`/`@returns` pairs. Kept the description
paragraphs and `@example` blocks, which accurately describe the
invokable methods. TypeScript's inferred types already provide the
correct parameter/return info for IDE tooltips.
Also updated the mirrored source text inside
`packages/hydrogen/docs/generated/generated_docs_data.json` so the
committed generated docs stay in sync with the source. The five
remaining `"The options for the cart query"` strings in that file
describe the factory functions themselves and are correct.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No functional change. Removes factually wrong JSDoc tags that currently surface in IDE tooltips and shopify.dev reference docs.
Problem
The four delivery-address fields on `HydrogenCart`
(`addDeliveryAddresses`, `removeDeliveryAddresses`,
`updateDeliveryAddresses`, `replaceDeliveryAddresses`) have JSDoc that
was copy-pasted from the factory functions in
`packages/hydrogen/src/cart/queries/cartDeliveryAddresses*Default.tsx`.
The factory functions take `(options: CartQueryOptions)` and return the
invokable method:
```ts
export function cartDeliveryAddressesAddDefault(
options: CartQueryOptions,
): CartDeliveryAddressesAddFunction { ... }
```
But the fields on `HydrogenCart` are the already-built methods:
```ts
addDeliveryAddresses: ReturnType;
// resolves to CartDeliveryAddressesAddFunction, which is:
(addresses: Array, optionalParams?: CartOptionalInput) => Promise
```
So every `@param {CartQueryOptions} options` and
`@returns {...Function} - A function that takes an array of addresses...`
on these fields is describing the wrong function. When a consumer hovers
`cart.addDeliveryAddresses` in an IDE, the tooltip currently says
`options: CartQueryOptions` — but the method actually takes
`(addresses, optionalParams?)`. Same misleading text ends up in the
reference docs generated from this file.
Same issue exists on all four delivery-address fields, plus the
`updateDeliveryAddresses` block also uses 2-space JSDoc indent (the
others use 3-space) and has a malformed example missing the `@example`
tag and `*` prefixes — those quirks are left alone here since they're
editorial and can go in a follow-up if anyone cares.
Fix
Removed the four wrong `@param`/`@returns` pairs. Kept the description
paragraphs and `@example` blocks, which accurately describe the
invokable methods. TypeScript's inferred types already give IDE
tooltips the correct parameter and return info, so nothing is lost.
The 12 other fields on `HydrogenCart` (`get`, `create`, `addLines`,
`updateLines`, etc.) have no JSDoc at all, so removing these tags
brings the delivery-address fields closer to the file's existing
convention.
Full-path trace
exposed through `createHydrogenContext` as `context.cart`.
(`cart.addDeliveryAddresses(...)` etc.) — no internal caller passes
`CartQueryOptions` to them, so the wrong JSDoc was never matched by
any real call site.
`packages/hydrogen/src/cart/queries/cartDeliveryAddresses*Default.tsx`
are correct (they do take `options: CartQueryOptions`) and are left
untouched.
the `HydrogenCart` type source as a `value` string. Updated that
string in the same commit so the committed generated docs stay in
sync. The five remaining `"The options for the cart query"` matches
in that file are legitimate factory-function parameter descriptions.
Changeset
None — the Changeset Reminder workflow excludes simple doc updates
("If you are making simple updates to examples or documentation, you
do not need to add a changeset."), and this change is entirely inside
JSDoc comments. No code, types, or runtime behaviour touched.