Add request options documentation parts to find-record builder (#8848)

packages/active-record/src/-private/builders/find-record.ts

@@ -48,6 +48,27 @@ type FindRecordOptions = ConstrainedRequestOptions & {
  * const data = await store.request(options);
  * ```
  *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and underscoring the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/active-record/request';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });
+ * const data = await store.request(options);
+ * ```
+ *
  * @method findRecord
  * @public
  * @static

packages/json-api/src/-private/builders/find-record.ts

@@ -42,6 +42,27 @@ import { copyForwardUrlOptions, extractCacheOptions } from './-utils';
  * const data = await store.request(options);
  * ```
  *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/json-api/request';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });
+ * const data = await store.request(options);
+ * ```
+ *
  * @method findRecord
  * @public
  * @static

packages/request-utils/src/index.ts

@@ -67,11 +67,11 @@ let CONFIG: BuildURLConfig = {
  * This method may be called as many times as needed
  *
  * ```ts
-   type BuildURLConfig = {
-     host: string;
-     namespace: string'
-   }
-   ```
+ * type BuildURLConfig = {
+ *   host: string;
+ *   namespace: string'
+ * }
+ * ```
  *
  * @method setBuildURLConfig
  * @static
@@ -336,7 +336,7 @@ function handleInclude(include: string | string[]): string[] {
 }
 
 /**
- * filter out keys of an object that have falsey values or point to empty arrays
+ * filter out keys of an object that have falsy values or point to empty arrays
  * returning a new object with only those keys that have truthy values / non-empty arrays
  *
  * @method filterEmpty
@@ -487,31 +487,30 @@ const NUMERIC_KEYS = new Set(['max-age', 's-maxage', 'stale-if-error', 'stale-wh
 /**
  *  Parses a string Cache-Control header value into an object with the following structure:
  *
-   ```ts
-   interface CacheControlValue {
-     immutable?: boolean;
-     'max-age'?: number;
-     'must-revalidate'?: boolean;
-     'must-understand'?: boolean;
-     'no-cache'?: boolean;
-     'no-store'?: boolean;
-     'no-transform'?: boolean;
-     'only-if-cached'?: boolean;
-     private?: boolean;
-     'proxy-revalidate'?: boolean;
-     public?: boolean;
-     's-maxage'?: number;
-     'stale-if-error'?: number;
-     'stale-while-revalidate'?: number;
-   }
-   ```
-
-  * @method parseCacheControl
-  * @static
-  * @public
-  * @for @ember-data/request-utils
-  * @param {string} header
-  * @returns {CacheControlValue}
+ * ```ts
+ * interface CacheControlValue {
+ *   immutable?: boolean;
+ *   'max-age'?: number;
+ *   'must-revalidate'?: boolean;
+ *   'must-understand'?: boolean;
+ *   'no-cache'?: boolean;
+ *   'no-store'?: boolean;
+ *   'no-transform'?: boolean;
+ *   'only-if-cached'?: boolean;
+ *   private?: boolean;
+ *   'proxy-revalidate'?: boolean;
+ *   public?: boolean;
+ *   's-maxage'?: number;
+ *   'stale-if-error'?: number;
+ *   'stale-while-revalidate'?: number;
+ * }
+ * ```
+ * @method parseCacheControl
+ * @static
+ * @public
+ * @for @ember-data/request-utils
+ * @param {string} header
+ * @returns {CacheControlValue}
  */
 export function parseCacheControl(header: string): CacheControlValue {
   let key = '';

packages/rest/src/-private/builders/find-record.ts

@@ -48,6 +48,27 @@ type FindRecordOptions = ConstrainedRequestOptions & {
  * const data = await store.request(options);
  * ```
  *
+ * **Supplying Options to Modify the Request Behavior**
+ *
+ * The following options are supported:
+ *
+ * - `host` - The host to use for the request, defaults to the `host` configured with `setBuildURLConfig`.
+ * - `namespace` - The namespace to use for the request, defaults to the `namespace` configured with `setBuildURLConfig`.
+ * - `resourcePath` - The resource path to use for the request, defaults to pluralizing and camelCasing the supplied type
+ * - `reload` - Whether to forcibly reload the request if it is already in the store, not supplying this
+ *      option will delegate to the store's lifetimes service, defaulting to `false` if none is configured.
+ * - `backgroundReload` - Whether to reload the request if it is already in the store, but to also resolve the
+ *      promise with the cached value, not supplying this option will delegate to the store's lifetimes service,
+ *      defaulting to `false` if none is configured.
+ * - `urlParamsSetting` - an object containing options for how to serialize the query params (see `buildQueryParams`)
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/rest/request';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] }, { namespace: 'api/v2' });
+ * const data = await store.request(options);
+ * ```
+ *
  * @method findRecord
  * @public
  * @static