Update JSDoc usage & fix minor JSDoc spelling typos (#2638)

* Improve usage of JSDoc `@see` directive when referencing links

This provides a better developer experience with highlighted links

* Fix typos in JSDoc & align to JSDoc formatting

* Fix typo in skeleton docs - predictiveSeach

* Ensure JSDoc comment is directly above annotated funcion

* Fix other small typos in variable names & JSDoc

examples/b2b/app/routes/account_.logout.tsx

@@ -1,6 +1,6 @@
 import {redirect, type ActionFunctionArgs} from '@shopify/remix-oxygen';
 
-// if we dont implement this, /account/logout will get caught by account.$.tsx to do login
+// if we don't implement this, /account/logout will get caught by account.$.tsx to do login
 export async function loader() {
   return redirect('/');
 }

packages/cli/assets/tailwind/tailwind.css

@@ -1,6 +1,6 @@
 /**
  * Configure Tailwind v4 in this file using CSS variables and directives:
- * https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration 
+ * https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration
  */
 
 @import 'tailwindcss';

packages/cli/scripts/generate-manifest.mjs

@@ -1,7 +1,7 @@
-/*
+/**
  * To avoid installing `oclif` as a dependency, this file mimics
  * how the manifest is generated by @oclif/core.
- * https://github.com/oclif/oclif/blob/main/src/commands/manifest.ts#L76
+ * @see https://github.com/oclif/oclif/blob/main/src/commands/manifest.ts#L76
  */
 
 import path from 'node:path';

packages/hydrogen-react/docs/generated/generated_docs_data.json

@@ -655,7 +655,7 @@
             "filePath": "src/CartProvider.tsx",
             "syntaxKind": "TypeAliasDeclaration",
             "name": "CartProviderProps",
-            "value": "{\n  /** Any `ReactNode` elements. */\n  children: React.ReactNode;\n  /**  Maximum number of cart lines to fetch. Defaults to 250 cart lines. */\n  numCartLines?: number;\n  /** A callback that is invoked when the process to create a cart begins, but before the cart is created in the Storefront API. */\n  onCreate?: () => void;\n  /** A callback that is invoked when the process to add a line item to the cart begins, but before the line item is added to the Storefront API. */\n  onLineAdd?: () => void;\n  /** A callback that is invoked when the process to remove a line item to the cart begins, but before the line item is removed from the Storefront API. */\n  onLineRemove?: () => void;\n  /** A callback that is invoked when the process to update a line item in the cart begins, but before the line item is updated in the Storefront API. */\n  onLineUpdate?: () => void;\n  /** A callback that is invoked when the process to add or update a note in the cart begins, but before the note is added or updated in the Storefront API. */\n  onNoteUpdate?: () => void;\n  /** A callback that is invoked when the process to update the buyer identity begins, but before the buyer identity is updated in the Storefront API. */\n  onBuyerIdentityUpdate?: () => void;\n  /** A callback that is invoked when the process to update the cart attributes begins, but before the attributes are updated in the Storefront API. */\n  onAttributesUpdate?: () => void;\n  /** A callback that is invoked when the process to update the cart discount codes begins, but before the discount codes are updated in the Storefront API. */\n  onDiscountCodesUpdate?: () => void;\n  /** A callback that is invoked when the process to create a cart completes */\n  onCreateComplete?: () => void;\n  /** A callback that is invoked when the process to add a line item to the cart completes */\n  onLineAddComplete?: () => void;\n  /** A callback that is invoked when the process to remove a line item to the cart completes */\n  onLineRemoveComplete?: () => void;\n  /** A callback that is invoked when the process to update a line item in the cart completes */\n  onLineUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to add or update a note in the cart completes */\n  onNoteUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to update the buyer identity completes */\n  onBuyerIdentityUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to update the cart attributes completes */\n  onAttributesUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to update the cart discount codes completes */\n  onDiscountCodesUpdateComplete?: () => void;\n  /** An object with fields that correspond to the Storefront API's [Cart object](https://shopify.dev/api/storefront/2024-10/objects/cart). */\n  data?: PartialDeep<CartType, {recurseIntoArrays: true}>;\n  /** A fragment used to query the Storefront API's [Cart object](https://shopify.dev/api/storefront/2024-10/objects/cart) for all queries and mutations. A default value is used if no argument is provided. */\n  cartFragment?: string;\n  /** A customer access token that's accessible on the server if there's a customer login. */\n  customerAccessToken?: CartBuyerIdentityInput['customerAccessToken'];\n  /** The ISO country code for i18n. */\n  countryCode?: CountryCode;\n  /** The ISO luanguage code for i18n. */\n  languageCode?: LanguageCode;\n}",
+            "value": "{\n  /** Any `ReactNode` elements. */\n  children: React.ReactNode;\n  /**  Maximum number of cart lines to fetch. Defaults to 250 cart lines. */\n  numCartLines?: number;\n  /** A callback that is invoked when the process to create a cart begins, but before the cart is created in the Storefront API. */\n  onCreate?: () => void;\n  /** A callback that is invoked when the process to add a line item to the cart begins, but before the line item is added to the Storefront API. */\n  onLineAdd?: () => void;\n  /** A callback that is invoked when the process to remove a line item to the cart begins, but before the line item is removed from the Storefront API. */\n  onLineRemove?: () => void;\n  /** A callback that is invoked when the process to update a line item in the cart begins, but before the line item is updated in the Storefront API. */\n  onLineUpdate?: () => void;\n  /** A callback that is invoked when the process to add or update a note in the cart begins, but before the note is added or updated in the Storefront API. */\n  onNoteUpdate?: () => void;\n  /** A callback that is invoked when the process to update the buyer identity begins, but before the buyer identity is updated in the Storefront API. */\n  onBuyerIdentityUpdate?: () => void;\n  /** A callback that is invoked when the process to update the cart attributes begins, but before the attributes are updated in the Storefront API. */\n  onAttributesUpdate?: () => void;\n  /** A callback that is invoked when the process to update the cart discount codes begins, but before the discount codes are updated in the Storefront API. */\n  onDiscountCodesUpdate?: () => void;\n  /** A callback that is invoked when the process to create a cart completes */\n  onCreateComplete?: () => void;\n  /** A callback that is invoked when the process to add a line item to the cart completes */\n  onLineAddComplete?: () => void;\n  /** A callback that is invoked when the process to remove a line item to the cart completes */\n  onLineRemoveComplete?: () => void;\n  /** A callback that is invoked when the process to update a line item in the cart completes */\n  onLineUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to add or update a note in the cart completes */\n  onNoteUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to update the buyer identity completes */\n  onBuyerIdentityUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to update the cart attributes completes */\n  onAttributesUpdateComplete?: () => void;\n  /** A callback that is invoked when the process to update the cart discount codes completes */\n  onDiscountCodesUpdateComplete?: () => void;\n  /** An object with fields that correspond to the Storefront API's [Cart object](https://shopify.dev/api/storefront/2024-10/objects/cart). */\n  data?: PartialDeep<CartType, {recurseIntoArrays: true}>;\n  /** A fragment used to query the Storefront API's [Cart object](https://shopify.dev/api/storefront/2024-10/objects/cart) for all queries and mutations. A default value is used if no argument is provided. */\n  cartFragment?: string;\n  /** A customer access token that's accessible on the server if there's a customer login. */\n  customerAccessToken?: CartBuyerIdentityInput['customerAccessToken'];\n  /** The ISO country code for i18n. */\n  countryCode?: CountryCode;\n  /** The ISO language code for i18n. */\n  languageCode?: LanguageCode;\n}",
             "description": "",
             "members": [
               {
@@ -702,7 +702,7 @@
                 "syntaxKind": "PropertySignature",
                 "name": "languageCode",
                 "value": "LanguageCode",
-                "description": "The ISO luanguage code for i18n.",
+                "description": "The ISO language code for i18n.",
                 "isOptional": true
               },
               {

packages/hydrogen-react/src/AddToCartButton.tsx

@@ -107,7 +107,7 @@ export function AddToCartButton<AsType extends React.ElementType = 'button'>(
   );
 }
 
-// This is only for documenation purposes, and it is not used in the code.
+// This is only for documentation purposes, and it is not used in the code.
 export interface AddToCartButtonPropsForDocs<
   AsType extends React.ElementType = 'button',
 > extends AddToCartButtonPropsBase,

packages/hydrogen-react/src/BuyNowButton.tsx

@@ -76,7 +76,7 @@ export function BuyNowButton<AsType extends React.ElementType = 'button'>(
   );
 }
 
-// This is only for documenation purposes, and it is not used in the code.
+// This is only for documentation purposes, and it is not used in the code.
 export interface BuyNowButtonPropsForDocs<
   AsType extends React.ElementType = 'button',
 > extends BuyNowButtonPropsBase,

packages/hydrogen-react/src/CartCost.tsx

@@ -42,7 +42,7 @@ export function CartCost(props: CartCostProps): JSX.Element | null {
   );
 }
 
-// This is only for documenation purposes, and it is not used in the code.
+// This is only for documentation purposes, and it is not used in the code.
 export interface CartCostPropsForDocs<AsType extends React.ElementType = 'div'>
   extends Omit<MoneyPropsBase<AsType>, 'data'>,
     CartCostPropsBase {}

packages/hydrogen-react/src/CartProvider.tsx

@@ -96,7 +96,7 @@ type CartProviderProps = {
   customerAccessToken?: CartBuyerIdentityInput['customerAccessToken'];
   /** The ISO country code for i18n. */
   countryCode?: CountryCode;
-  /** The ISO luanguage code for i18n. */
+  /** The ISO language code for i18n. */
   languageCode?: LanguageCode;
 };
 
@@ -531,8 +531,9 @@ function useDelayedStateUntilHydration<T>(state: T): T {
   return displayState;
 }
 
-/** Check for storage availability funciton obtained from
- * https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API
+/**
+ * Check for storage availability function obtained from
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API
  */
 export function storageAvailable(
   type: 'localStorage' | 'sessionStorage',

packages/hydrogen-react/src/ExternalVideo.tsx

@@ -24,7 +24,6 @@ export type ExternalVideoProps = Omit<
  * The `ExternalVideo` component renders an embedded video for the Storefront
  * API's [ExternalVideo object](https://shopify.dev/api/storefront/reference/products/externalvideo).
  */
-
 export const ExternalVideo = forwardRef<HTMLIFrameElement, ExternalVideoProps>(
   (props, ref): JSX.Element => {
     const {

packages/hydrogen-react/src/ProductPrice.tsx

@@ -100,7 +100,7 @@ export function ProductPrice<
   return <Money {...passthroughProps} data={price} />;
 }
 
-// This is only for documenation purposes, and it is not used in the code.
+// This is only for documentation purposes, and it is not used in the code.
 export interface ProductPricePropsForDocs<
   AsType extends React.ElementType = 'div',
 > extends Omit<MoneyPropsBase<AsType>, 'data' | 'measurement'>,

packages/hydrogen-react/src/RichText.tsx

@@ -208,6 +208,6 @@ function richTextToString(
   return result.join('').trim();
 }
 
-// This is only for documenation purposes, and it is not used in the code.
+// This is only for documentation purposes, and it is not used in the code.
 export type RichTextPropsForDocs<AsType extends React.ElementType = 'div'> =
   RichTextPropsBase<AsType>;

packages/hydrogen-react/src/storefront-api-response.types.ts

@@ -8,7 +8,7 @@ import type {PartialDeep} from 'type-fest';
 type StorefrontApiExtensions = {
   /**
    * Shows error codes common to Shopify. Additional error codes may also be shown.
-   * https://shopify.dev/api/storefront#status_and_error_codes
+   * @see https://shopify.dev/api/storefront#status_and_error_codes
    */
   code?:
     | 'THROTTLED'
@@ -22,7 +22,7 @@ type StorefrontApiExtensions = {
 /**
  * The Storefront API can return a 200 OK response code when the query succeeds, and will populate the `data` property. The generic you pass in through type parameters will be the shape of the `data` object if successful. If you prefer a "deeply-partial" version of that generic object, consider using `StorefrontApiResponseOkPartial` instead.
  *
- * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will propulate the `errors` property.
+ * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will populate the `errors` property.
  *
  * Refer to https://shopify.dev/api/storefront#status_and_error_codes for more information.
  */
@@ -34,7 +34,7 @@ export type StorefrontApiResponseOk<DataGeneric> = FormattedExecutionResult<
 /**
  * The Storefront API can return a 200 OK response code when the query succeeds, and will populate the `data` property. The generic you pass in through type parameters will be the shape of the `data` object, with `Partial` deeply-applied to all nested objects and properties, if successful. If you prefer not using this "deeply-partial" generic data object, consider using `StorefrontApiResponseOk` instead.
  *
- * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will propulate the `errors` property.
+ * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will populate the `errors` property.
  *
  * Refer to https://shopify.dev/api/storefront#status_and_error_codes for more information.
  */
@@ -63,7 +63,7 @@ export type StorefrontApiResponseError =
 /**
  * The Storefront API can return a 200 OK response code when the query succeeds, and will populate the `data` property. The generic you pass in through type parameters will be the shape of the `data` object if successful. If you prefer a "deeply-partial" version of that generic object, consider using `StorefrontApiResponseOkPartial` instead.
  *
- * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will propulate the `errors` property.
+ * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will populate the `errors` property.
  *
  * 4xx and 5xx errors occur infrequently. They are often related to network communications, your account, or an issue with Shopify’s services.  Commonly the response is a `JSON.parse`-able string, but in rare occasions may also return HTML which is not `JSON.parse()`-able.
  *
@@ -76,7 +76,7 @@ export type StorefrontApiResponse<DataGeneric> =
 /**
  * The Storefront API can return a 200 OK response code when the query succeeds, and will populate the `data` property. The generic you pass in through type parameters will be the shape of the `data` object, with `Partial` deeply-applied to all nested objects and properties, if successful. If you prefer not using this "deeply-partial" generic data object, consider using `StorefrontApiResponseOk` instead.
  *
- * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will propulate the `errors` property.
+ * The Storefront API can also return a 200 OK response code in cases that would typically produce 4xx errors in REST. This will populate the `errors` property.
  *
  * 4xx and 5xx errors occur infrequently. They are often related to network communications, your account, or an issue with Shopify’s services. Commonly the response is a `JSON.parse`-able string, but in rare occasions may also return HTML which is not `JSON.parse()`-able.
  *

packages/hydrogen/src/analytics-manager/AnalyticsProvider.tsx

@@ -272,8 +272,10 @@ function register(key: string) {
   };
 }
 
-// This functions attempts to automatically determine if the user can be tracked if the
-// customer privacy API is available. If not, it will default to false.
+/**
+ * This functions attempts to automatically determine if the user can be tracked if the
+ * customer privacy API is available. If not, it will default to false.
+ */
 function shopifyCanTrack(): boolean {
   try {
     return window.Shopify.customerPrivacy.analyticsProcessingAllowed();

packages/mini-oxygen/src/worker/assets.ts

@@ -24,7 +24,7 @@ export function buildAssetsUrl(assetsPort: number) {
  * Note: this is not used when running with Vite because it already
  * serves transformed assets before reaching MiniOxygen.
  * See the following for more details:
- * https://github.com/Shopify/hydrogen/pull/2078#issuecomment-2121705993
+ * @see https://github.com/Shopify/hydrogen/pull/2078#issuecomment-2121705993
  */
 export function createAssetsServer(assetsDirectory: string) {
   return createServer(async (req: IncomingMessage, res: ServerResponse) => {

packages/mini-oxygen/src/worker/inspector.ts

@@ -1,6 +1,6 @@
 /**
  * Huge part of this code comes from Wrangler:
- * https://github.com/cloudflare/workers-sdk/blob/main/packages/wrangler/src/inspect.ts
+ * @see https://github.com/cloudflare/workers-sdk/blob/main/packages/wrangler/src/inspect.ts
  */
 
 import {dirname} from 'node:path';
@@ -12,7 +12,9 @@ import {type Protocol} from 'devtools-protocol';
 import {addInspectorConsoleLogger, formatStack} from './logger.js';
 import {createInspectorProxy, type InspectorProxy} from './devtools.js';
 
-// https://chromedevtools.github.io/devtools-protocol/#endpoints
+/**
+ * @see https://chromedevtools.github.io/devtools-protocol/#endpoints
+ */
 export interface InspectorWebSocketTarget {
   id: string;
   title: string;
@@ -50,7 +52,7 @@ export interface ErrorProperties {
  * Creates a connection to the workerd inspector.
  *
  * The messages are sent via WebSockets following the Chrome DevTools Protocol:
- * https://chromedevtools.github.io/devtools-protocol/
+ * @see https://chromedevtools.github.io/devtools-protocol/
  *
  * The inspector connection has two purposes:
  * 1. Attach debuggers to the workerd instance.

templates/skeleton/app/components/PaginatedResourceSection.tsx

@@ -4,7 +4,6 @@ import {Pagination} from '@shopify/hydrogen';
 /**
  * <PaginatedResourceSection > is a component that encapsulate how the previous and next behaviors throughout your application.
  */
-
 export function PaginatedResourceSection<NodesType>({
   connection,
   children,

templates/skeleton/app/components/SearchResultsPredictive.tsx

@@ -133,15 +133,15 @@ function SearchResultsPredictiveCollections({
       <h5>Collections</h5>
       <ul>
         {collections.map((collection) => {
-          const colllectionUrl = urlWithTrackingParams({
+          const collectionUrl = urlWithTrackingParams({
             baseUrl: `/collections/${collection.handle}`,
             trackingParams: collection.trackingParameters,
             term: term.current,
           });
 
           return (
             <li className="predictive-search-result-item" key={collection.id}>
-              <Link onClick={closeSearch} to={colllectionUrl}>
+              <Link onClick={closeSearch} to={collectionUrl}>
                 {collection.image?.url && (
                   <Image
                     alt={collection.image.altText ?? ''}

templates/skeleton/app/routes/account_.logout.tsx

@@ -1,6 +1,6 @@
 import {redirect, type ActionFunctionArgs} from '@shopify/remix-oxygen';
 
-// if we dont implement this, /account/logout will get caught by account.$.tsx to do login
+// if we don't implement this, /account/logout will get caught by account.$.tsx to do login
 export async function loader() {
   return redirect('/');
 }

templates/skeleton/guides/predictiveSearch/predictiveSearch.md

@@ -157,7 +157,7 @@ const PREDICTIVE_SEARCH_QUERY = `#graphql
 /**
  * Predictive search fetcher
  */
-async function predictiveSeach({
+async function predictiveSearch({
   request,
   context,
 }: Pick<ActionFunctionArgs, 'request' | 'context'>) {