Merge pull request #445 from Shopify/docs_improvements

Improvements to docs copy

.changeset/cold-starfishes-sell.md

@@ -0,0 +1,2 @@
+---
+---

packages/shopify-app-remix/docs/generated/generated_static_pages.json

@@ -8,7 +8,7 @@
         "type": "Generic",
         "anchorLink": "auth",
         "title": "Authenticating requests",
-        "sectionContent": "To authenticate admin requests you can call `authenticate.admin(request)` in a loader or an action.\n\nIf there is a session for this user, this loader will return null. If there is no session for the user, the loader will throw the appropriate redirect Response.\n\n> Tip: If you are authenticating more than one route, we recommend using [Remix layout routes](https://remix.run/docs/en/1.18.1/file-conventions/routes-files#layout-routes) to automatically authenticate them.",
+        "sectionContent": "To authenticate admin requests you can call `authenticate.admin(request)` in a loader or an action.\n\nIf there's a session for this user, then this loader will return null. If there's no session for the user, then the loader will throw the appropriate redirect Response.\n\n> Tip: If you are authenticating more than one route, then we recommend using [Remix layout routes](https://remix.run/docs/en/1.18.1/file-conventions/routes-files#layout-routes) to automatically authenticate them.",
         "codeblock": {
           "title": "/app/routes/**/*.tsx",
           "tabs": [
@@ -40,7 +40,7 @@
         "type": "Generic",
         "anchorLink": "cors-auth",
         "title": "Authenticating cross-origin admin requests",
-        "sectionContent": "If your Remix server is authenticating an admin extension, a request from the extension to Remix will be cross-origin.\n\nHere `authenticate.admin` provides a `cors` function to add the required cross-origin headers.",
+        "sectionContent": "If your Remix server is authenticating an admin extension, then a request from the extension to Remix will be cross-origin.\n\nHere `authenticate.admin` provides a `cors` function to add the required cross-origin headers.",
         "codeblock": {
           "title": "/app/routes/**/*.tsx",
           "tabs": [
@@ -56,7 +56,7 @@
         "type": "Generic",
         "anchorLink": "graphql-api",
         "title": "Using the GraphQL API",
-        "sectionContent": "Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a GraphQL client that can interact with the [Shopify Admin GraphQL API](/docs/api/admin-graphql).",
+        "sectionContent": "Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a GraphQL client that can interact with the [GraphQL Admin API](/docs/api/admin-graphql).",
         "codeblock": {
           "title": "/app/routes/**/*.tsx",
           "tabs": [
@@ -72,7 +72,7 @@
         "type": "Generic",
         "anchorLink": "rest-api",
         "title": "Using the REST API",
-        "sectionContent": "Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a REST client that can interact with the [Shopify Admin REST API](/docs/api/admin-rest).\n\nYou can also import a set of resource classes from the `@shopify/shopify-api` package (included in `@shopify/shopify-app-remix`).\n\nThese classes map to the individual REST endpoints, and will be returned under `admin.rest.resources`.",
+        "sectionContent": "Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a REST client that can interact with the [REST Admin API](/docs/api/admin-rest).\n\nYou can also import a set of resource classes from the `@shopify/shopify-api` package, which is included in `@shopify/shopify-app-remix`.\n\nThese classes map to the individual REST endpoints, and will be returned under `admin.rest.resources`.",
         "codeblock": {
           "title": "Interacting with the REST API",
           "tabs": [
@@ -109,9 +109,9 @@
     "sections": [
       {
         "type": "Generic",
-        "anchorLink": "install",
-        "title": "Install",
-        "sectionContent": "If you're not using the CLI, you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
+        "anchorLink": "installation",
+        "title": "Installation",
+        "sectionContent": "If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
         "sectionCard": [
           {
             "name": "Build an app",
@@ -271,7 +271,7 @@
         "type": "Generic",
         "anchorLink": "endpoints",
         "title": "Set up your endpoints",
-        "sectionContent": "Legitimate webhook requests are always `POST`s signed by Shopify, so you must authenticate them before taking any action.\n\nFor each `callbackUrl` in your configuration, you must set up an `action` that uses the `authenticate.webhook` function to authenticate the request.\n\nPlease keep in mind that webhook endpoints should respond as quickly as possible. If you need to run a long-running job, consider using background tasks.\n\n> Caution: Webhook endpoints **must** respond with an `HTTP 200` code, or Shopify will retry.",
+        "sectionContent": "Legitimate webhook requests are always `POST`s signed by Shopify, so you must authenticate them before taking any action.\n\nFor each `callbackUrl` in your configuration, you must set up an `action` that uses the `authenticate.webhook` function to authenticate the request.\n\nPlease keep in mind that webhook endpoints should respond as quickly as possible. If you need to run a long-running job, then consider using background tasks.\n\n> Caution: Webhook endpoints **must** respond with an `HTTP 200` code, or Shopify will retry.",
         "codeblock": {
           "title": "/app/routes/webhooks.tsx",
           "tabs": [

packages/shopify-app-remix/docs/staticPages/admin.doc.ts

@@ -14,9 +14,9 @@ const data: LandingTemplateSchema = {
       anchorLink: 'auth',
       title: 'Authenticating requests',
       sectionContent:
-        'To authenticate admin requests you can call `authenticate.admin(request)` in a loader or an action.' +
-        '\n\nIf there is a session for this user, this loader will return null. If there is no session for the user, the loader will throw the appropriate redirect Response.' +
-        '\n\n> Tip: If you are authenticating more than one route, we recommend using [Remix layout routes](https://remix.run/docs/en/1.18.1/file-conventions/routes-files#layout-routes) to automatically authenticate them.',
+        "To authenticate admin requests you can call `authenticate.admin(request)` in a loader or an action." +
+        "\n\nIf there's a session for this user, then this loader will return null. If there's no session for the user, then the loader will throw the appropriate redirect Response." +
+        "\n\n> Tip: If you are authenticating more than one route, then we recommend using [Remix layout routes](https://remix.run/docs/en/1.18.1/file-conventions/routes-files#layout-routes) to automatically authenticate them.",
       codeblock: {
         title: '/app/routes/**/*.tsx',
         tabs: [
@@ -52,7 +52,7 @@ const data: LandingTemplateSchema = {
       anchorLink: 'cors-auth',
       title: 'Authenticating cross-origin admin requests',
       sectionContent:
-        'If your Remix server is authenticating an admin extension, a request from the extension to Remix will be cross-origin.' +
+        'If your Remix server is authenticating an admin extension, then a request from the extension to Remix will be cross-origin.' +
         '\n\nHere `authenticate.admin` provides a `cors` function to add the required cross-origin headers.',
       codeblock: {
         title: '/app/routes/**/*.tsx',
@@ -70,7 +70,7 @@ const data: LandingTemplateSchema = {
       anchorLink: 'graphql-api',
       title: 'Using the GraphQL API',
       sectionContent:
-        'Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a GraphQL client that can interact with the [Shopify Admin GraphQL API](/docs/api/admin-graphql).',
+        'Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a GraphQL client that can interact with the [GraphQL Admin API](/docs/api/admin-graphql).',
       codeblock: {
         title: '/app/routes/**/*.tsx',
         tabs: [
@@ -87,8 +87,8 @@ const data: LandingTemplateSchema = {
       anchorLink: 'rest-api',
       title: 'Using the REST API',
       sectionContent:
-        'Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a REST client that can interact with the [Shopify Admin REST API](/docs/api/admin-rest).' +
-        '\n\nYou can also import a set of resource classes from the `@shopify/shopify-api` package (included in `@shopify/shopify-app-remix`).' +
+        'Once a request is authenticated, `authenticate.admin` will return an `admin` object that contains a REST client that can interact with the [REST Admin API](/docs/api/admin-rest).' +
+        '\n\nYou can also import a set of resource classes from the `@shopify/shopify-api` package, which is included in `@shopify/shopify-app-remix`.' +
         '\n\nThese classes map to the individual REST endpoints, and will be returned under `admin.rest.resources`.',
       codeblock: {
         title: 'Interacting with the REST API',

packages/shopify-app-remix/docs/staticPages/index.doc.ts

@@ -10,10 +10,10 @@ const data: LandingTemplateSchema = {
   sections: [
     {
       type: 'Generic',
-      anchorLink: 'install',
-      title: 'Install',
+      anchorLink: 'installation',
+      title: 'Installation',
       sectionContent:
-        "If you're not using the CLI, you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
+        "If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
       sectionCard: [
         {
           name: 'Build an app',

packages/shopify-app-remix/docs/staticPages/webhooks.doc.ts

@@ -33,7 +33,7 @@ const data: LandingTemplateSchema = {
       sectionContent:
         'Legitimate webhook requests are always `POST`s signed by Shopify, so you must authenticate them before taking any action.' +
         '\n\nFor each `callbackUrl` in your configuration, you must set up an `action` that uses the `authenticate.webhook` function to authenticate the request.' +
-        '\n\nPlease keep in mind that webhook endpoints should respond as quickly as possible. If you need to run a long-running job, consider using background tasks.' +
+        '\n\nPlease keep in mind that webhook endpoints should respond as quickly as possible. If you need to run a long-running job, then consider using background tasks.' +
         '\n\n> Caution: Webhook endpoints **must** respond with an `HTTP 200` code, or Shopify will retry.',
       codeblock: {
         title: '/app/routes/webhooks.tsx',

packages/shopify-app-remix/src/react/components/AppProvider/AppProvider.tsx

@@ -36,7 +36,7 @@ export interface AppProviderProps
 }
 
 /**
- * Sets up the Polaris AppProvider and injects the App Bridge script.
+ * Sets up the Polaris `AppProvider` and injects the App Bridge script.
  *
  * This component extends the [`AppProvider`](https://polaris.shopify.com/components/utilities/app-provider) component
  * from Polaris, and accepts all of its props except for `linkComponent`, which is overridden to use the Remix `Link`

packages/shopify-app-remix/src/server/authenticate/admin/authenticate.admin.doc.ts

@@ -11,7 +11,7 @@ const data: ReferenceEntityTemplateSchema = {
     {
       title: 'authenticate.admin',
       description:
-        'Authenticates requests coming from Shopify Admin.\n\nThe shape of the returned object changes depending on the `isEmbeddedApp` config.',
+        'Authenticates requests coming from the Shopify admin.\n\nThe shape of the returned object changes depending on the `isEmbeddedApp` config.',
       type: 'AuthenticateAdmin',
     },
     {

packages/shopify-app-remix/src/server/authenticate/admin/types.ts

@@ -69,7 +69,7 @@ interface AdminContextInternal<
   session: Session;
 
   /**
-   * Methods for interacting with the Shopify GraphQL / REST Admin APIs for the store that made the request
+   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.
    */
   admin: AdminApiContext<Resources>;
 
@@ -81,7 +81,7 @@ interface AdminContextInternal<
   billing: BillingContext<Config>;
 
   /**
-   * A function that ensures the CORS headers are set correctly for the response
+   * A function that ensures the CORS headers are set correctly for the response.
    *
    * @example
    * <caption>Setting CORS headers for a admin request</caption>

packages/shopify-app-remix/src/server/authenticate/public/appProxy/types.ts

@@ -43,9 +43,10 @@ export interface AppProxyContext extends Context {
    * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
    */
   session: undefined;
+
   /**
    * No session is available for the shop that made this request.
-   * Therefore no methods for interacting with the Shopify GraphQL / REST Admin APIs are available.
+   * Therefore no methods for interacting with the GraphQL / REST Admin APIs are available.
    */
   admin: undefined;
 }
@@ -58,7 +59,7 @@ export interface AppProxyContextWithSession<
    *
    * This comes from the session storage which `shopifyApp` uses to store sessions in your database of choice.
    *
-   * Use this to get shop or user specific data.
+   * Use this to get shop or user-specific data.
    *
    * @example
    * <caption>Getting your app's shop specific widget data using an offline session</caption>
@@ -75,8 +76,9 @@ export interface AppProxyContextWithSession<
    * ```
    */
   session: Session;
+
   /**
-   * Methods for interacting with the Shopify GraphQL / REST Admin APIs for the store that made the request
+   * Methods for interacting with the GraphQL / REST Admin APIs for the store that made the request.
    */
   admin: AdminApiContext<Resources>;
 }

packages/shopify-app-remix/src/server/authenticate/public/checkout/types.ts

@@ -18,7 +18,7 @@ export interface CheckoutContext {
   /**
    * The decoded and validated session token for the request
    *
-   * The payload of the Session Token is described here: {@link https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload}
+   * Refer to the OAuth docs for the [session token payload](https://shopify.dev/docs/apps/auth/oauth/session-tokens#payload).
    *
    * @example
    * <caption>Get store specific widget data using the session token</caption>
@@ -39,7 +39,7 @@ export interface CheckoutContext {
   sessionToken: JwtPayload;
 
   /**
-   * A function that ensures the CORS headers are set correctly for the response
+   * A function that ensures the CORS headers are set correctly for the response.
    *
    * @example
    * <caption>Setting CORS headers for a public request</caption>

packages/shopify-app-remix/src/server/config-types.ts

@@ -280,7 +280,7 @@ export interface AdminApiContext<
   Resources extends ShopifyRestResources = ShopifyRestResources,
 > {
   /**
-   * Methods for interacting with the Shopify Admin REST API
+   * Methods for interacting with the REST Admin API.
    *
    * There are methods for interacting with individual REST resources. You can also make `GET`, `POST`, `PUT` and `DELETE` requests should the REST resources not meet your needs.
    *
@@ -345,7 +345,7 @@ export interface AdminApiContext<
   rest: RestClientWithResources<Resources>;
 
   /**
-   * Methods for interacting with the Shopify Admin GraphQL API
+   * Methods for interacting with the GraphQL Admin API.
    *
    * {@link https://shopify.dev/docs/api/admin-graphql}
    * {@link https://github.com/Shopify/shopify-api-js/blob/main/docs/reference/clients/Graphql.md}

packages/shopify-app-remix/src/server/shopify-app.doc.ts

@@ -4,7 +4,7 @@ const data: ReferenceEntityTemplateSchema = {
   name: 'shopifyApp',
   description:
     "Returns a set of functions that can be used by the app's backend to be able to respond to all Shopify requests." +
-    '\n\nThe shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included.' +
+    '\n\nThe shape of the returned object changes depending on the value of `distribution`. If it is `AppDistribution.ShopifyAdmin`, then only `ShopifyAppBase` objects are returned, otherwise `ShopifyAppLogin` objects are included.' +
     '\n\nRefer to the [Related](#related) section to see all supported contexts in `authenticate` and `unauthenticated`.',
   category: 'Entrypoints',
   type: 'function',

packages/shopify-app-remix/src/server/shopify-app.ts

@@ -34,7 +34,7 @@ import {authenticatePublicFactory} from './authenticate/public';
 /**
  * Creates an object your app will use to interact with Shopify.
  *
- * @param appConfig Configuration options for your shopify app.  For example, the scopes your app needs.
+ * @param appConfig Configuration options for your Shopify app, such as the scopes your app needs.
  * @returns `ShopifyApp` An object constructed using your appConfig.  It has methods for interacting with Shopify.
  *
  * @example

packages/shopify-app-remix/src/server/unauthenticated/admin/types.ts

@@ -30,7 +30,7 @@ export interface UnauthenticatedAdminContext<
   session: Session;
 
   /**
-   * Methods for interacting with the Shopify GraphQL / REST Admin APIs for the given store.
+   * Methods for interacting with the GraphQL / REST Admin APIs for the given store.
    */
   admin: AdminApiContext<Resources>;
 }

packages/shopify-app-remix/src/server/unauthenticated/admin/unauthenticated.admin.doc.ts

@@ -3,7 +3,11 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'Unauthenticated admin',
   description:
-    "Allows interacting with the Admin API on requests that didn't come from Shopify.\n\nRefer to the [Related](#related) section to see all supported actions in `admin`.\n\n> Caution: This should only be used for Requests that do not originate from Shopify.\n> You must do your own authentication before using this method.\n>This function doesn't perform **any** validation and should not rely on unvalidated user input.",
+    "Allows interacting with the Admin API on requests that didn't come from Shopify." +
+    '\n\nRefer to the [Related](#related) section to see all supported actions in `admin`.' +
+    '\n\n> Caution: This should only be used for Requests that do not originate from Shopify.' +
+    '\n> You must do your own authentication before using this method.' +
+    "\n>This function doesn't perform **any** validation and shouldn't rely on unvalidated user input.",
   category: 'Unauthenticated',
   type: 'object',
   isVisualComponent: false,