fix js doc comments

Author: laurelthorburn

packages/hydrogen-react/src/CartLineProvider.tsx

@@ -12,7 +12,9 @@ type CartLinePartialDeep = PartialDeep<
 
 export const CartLineContext = createContext<CartLinePartialDeep | null>(null);
 
-/** @publicDocs */
+/**
+ * The `useCartLine` hook provides access to the [CartLine object](https://shopify.dev/api/storefront/2026-01/objects/cartline) from the Storefront API. It must be a descendent of a `CartProvider` component.
+ */
 export function useCartLine(): CartLinePartialDeep {
   const context = useContext(CartLineContext);
 

packages/hydrogen-react/src/MediaFile.tsx

@@ -9,10 +9,7 @@ import type {ModelViewerElement} from '@google/model-viewer/lib/model-viewer.js'
 type BaseProps = React.HTMLAttributes<
   HTMLImageElement | HTMLVideoElement | HTMLIFrameElement | ModelViewerElement
 >;
-/**
- * MediaFile renders an `Image`, `Video`, `ExternalVideo`, or `ModelViewer` component. Use the `mediaOptions` prop to customize the props sent to each of these components.
- * @publicDocs
- */
+/** @publicDocs */
 export interface MediaFileProps extends BaseProps {
   /** An object with fields that correspond to the Storefront API's [Media object](https://shopify.dev/api/storefront/reference/products/media). */
   data: PartialDeep<MediaEdgeType['node'], {recurseIntoArrays: true}>;
@@ -38,7 +35,6 @@ type MediaOptions = {
  * The `MediaFile` component renders the media for the Storefront API's
  * [Media object](https://shopify.dev/api/storefront/reference/products/media). It renders an `Image`, a
  * `Video`, an `ExternalVideo`, or a `ModelViewer` depending on the `__typename` of the `data` prop.
- * Use the `mediaOptions` prop to customize the props sent to each of these components.
  * @publicDocs
  */
 export function MediaFile({

packages/hydrogen-react/src/ShopifyProvider.tsx

@@ -116,7 +116,10 @@ export function ShopifyProvider({
   );
 }
 
-/** @publicDocs */
+/**
+ * Provides access to the `shopifyConfig` prop of `<ShopifyProvider/>`. Must be a descendent of `<ShopifyProvider/>`.
+ * @publicDocs
+ */
 export function useShop(): ShopifyContextValue {
   const shopContext = useContext(ShopifyContext);
   if (!shopContext) {
@@ -149,7 +152,10 @@ export interface ShopifyProviderBase {
   sameDomainForStorefrontApi?: boolean;
 }
 
-/** @publicDocs */
+/**
+ * Shopify-specific values that are used in various Hydrogen React components and hooks.
+ * @publicDocs
+ */
 export interface ShopifyProviderProps extends ShopifyProviderBase {
   /** React children to render. */
   children?: ReactNode;

packages/hydrogen-react/src/analytics.ts

@@ -19,7 +19,14 @@ import {
 } from './analytics-schema-custom-storefront-customer-tracking.js';
 import {getTrackingValues} from './tracking-utils.js';
 
-/** @publicDocs */
+/**
+ * Set user and session cookies and refresh the expiry time
+ * @param event - The analytics event.
+ * @param shopDomain - The Online Store domain to sent Shopify analytics under the same
+ *   top level domain.
+ * @publicDocs
+ */
+
 export function sendShopifyAnalytics(
   event: ShopifyAnalytics,
   shopDomain?: string,

packages/hydrogen-react/src/cookies-utils.tsx

@@ -59,6 +59,7 @@ export function hexTime(): string {
 }
 
 /**
+ * Gets the values of _shopify_y and _shopify_s cookies from the provided cookie string.
  * @deprecated Use getTrackingValues instead.
  * @publicDocs
  */

packages/hydrogen-react/src/flatten-connection.ts

@@ -91,8 +91,5 @@ type ConnectionNodes = {
 export interface ConnectionGenericForDoc {
   connection?: ConnectionEdges | ConnectionNodes;
 }
-/**
- * The return type of the `flattenConnection` utility: a flat array of nodes extracted from a Storefront API connection object.
- * @publicDocs
- */
+/** @publicDocs */
 export type FlattenConnectionReturnForDoc = unknown[];

packages/hydrogen-react/src/optionValueDecoder.ts

@@ -20,10 +20,7 @@ const V1_CONTROL_CHARS = {
   RANGE: '-',
 };
 
-/**
- * A function type that determines whether a given option value combination is present in an encoded variant field from the Storefront API.
- * @publicDocs
- */
+/** @publicDocs */
 export type IsOptionValueCombinationInEncodedVariant = (
   targetOptionValueCombination: number[],
   encodedVariantField: string,

packages/hydrogen-react/src/parse-metafield.ts

@@ -13,7 +13,16 @@ import type {PartialDeep, Simplify} from 'type-fest';
 import {flattenConnection} from './flatten-connection.js';
 import {RootASTNode as RichTextRootASTNode} from './RichText.types.js';
 
-/** @publicDocs */
+/**
+ * A function that uses `metafield.type` to parse the Metafield's `value` or `reference` or `references` (depending on the `metafield.type`) and places the result in `metafield.parsedValue`
+ *
+ * TypeScript developers can use the type `ParsedMetafields` from this package to get the returned object's type correct. For example:
+ *
+ * ```
+ * parseMetafield<ParsedMetafields['boolean']>({type: 'boolean', value: 'false'}
+ * ```
+ * @publicDocs
+ */
 export function parseMetafield<ReturnGeneric>(
   metafield: PartialDeep<MetafieldBaseType, {recurseIntoArrays: true}>,
 ): ReturnGeneric {

packages/hydrogen-react/src/tracking-utils.ts

@@ -18,7 +18,11 @@ export const cachedTrackingValues: {
   current: null | TrackingValues;
 } = {current: null};
 
-/** @publicDocs */
+/**
+ * Retrieves user session tracking values for analytics
+ * and marketing from the browser environment.
+ * @publicDocs
+ */
 export function getTrackingValues(): TrackingValues {
   // Overall behavior: Tracking values are returned in Server-Timing headers from
   // Storefront API responses, and we want to find and return these tracking values.

packages/hydrogen-react/src/useMoney.tsx

@@ -72,7 +72,59 @@ export type UseMoneyValue = {
   withoutTrailingZerosAndCurrency: string;
 };
 
-/** @publicDocs */
+/**
+ * The `useMoney` hook takes a [MoneyV2 object from the Storefront API](https://shopify.dev/docs/api/storefront/2026-01/objects/MoneyV2)
+ * or a [MoneyV2 object from the Customer Account API](https://shopify.dev/docs/api/customer/2026-01/objects/moneyv2) and returns a
+ * default-formatted string of the amount with the correct currency indicator, along with some of the parts provided by
+ * [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
+ * Uses `locale` from `ShopifyProvider`
+ *  
+ * @see {@link https://shopify.dev/api/hydrogen/hooks/usemoney}
+ * @example initialize the money object
+ * ```ts
+ * const money = useMoney({
+ *   amount: '100.00',
+ *   currencyCode: 'USD'
+ * })
+ * ```
+ *  
+ *
+ * @example basic usage, outputs: $100.00
+ * ```ts
+ * money.localizedString
+ * ```
+ *  
+ *
+ * @example without currency, outputs: 100.00
+ * ```ts
+ * money.amount
+ * ```
+ *  
+ *
+ * @example without trailing zeros, outputs: $100
+ * ```ts
+ * money.withoutTrailingZeros
+ * ```
+ *  
+ *
+ * @example currency name, outputs: US dollars
+ * ```ts
+ * money.currencyCode
+ * ```
+ *  
+ *
+ * @example currency symbol, outputs: $
+ * ```ts
+ * money.currencySymbol
+ * ```
+ *  
+ *
+ * @example without currency and without trailing zeros, outputs: 100
+ * ```ts
+ * money.withoutTrailingZerosAndCurrency
+ * ```
+ * @publicDocs
+ */
 export function useMoney(money: MoneyV2): UseMoneyValue {
   const {countryIsoCode, languageIsoCode} = useShop();
   const locale = languageIsoCode.includes('_')