Skip to content

fix(hydrogen): remove wrong JSDoc @param/@returns on HydrogenCart delivery-address fields#3719

Open
andromia3 wants to merge 1 commit intoShopify:mainfrom
andromia3:fix/hydrogen-cart-jsdoc
Open

fix(hydrogen): remove wrong JSDoc @param/@returns on HydrogenCart delivery-address fields#3719
andromia3 wants to merge 1 commit intoShopify:mainfrom
andromia3:fix/hydrogen-cart-jsdoc

Conversation

@andromia3
Copy link
Copy Markdown

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

  • `HydrogenCart` is the public type returned by `createCartHandler` and
    exposed through `createHydrogenContext` as `context.cart`.
  • All four affected fields are consumed through the cart handler pattern
    (`cart.addDeliveryAddresses(...)` etc.) — no internal caller passes
    `CartQueryOptions` to them, so the wrong JSDoc was never matched by
    any real call site.
  • The factory-function JSDoc blocks in
    `packages/hydrogen/src/cart/queries/cartDeliveryAddresses*Default.tsx`
    are correct (they do take `options: CartQueryOptions`) and are left
    untouched.
  • `packages/hydrogen/docs/generated/generated_docs_data.json` mirrors
    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.

…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.
@andromia3 andromia3 requested a review from a team as a code owner April 14, 2026 15:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant