feat: more docs for builders (#8825)

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

@@ -1,3 +1,6 @@
+/**
+ * @module @ember-data/active-record/request
+ */
 import { underscore } from '@ember/string';
 
 import { pluralize } from 'ember-inflector';
@@ -15,6 +18,43 @@ type FindRecordOptions = ConstrainedRequestOptions & {
   include?: string | string[];
 };
 
+/**
+ * Builds request options to fetch a single resource by a known id or identifier
+ * configured for the url and header expectations of most JSON:API APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/active-record/request';
+ *
+ * const data = await store.request(findRecord('person', '1'));
+ * ```
+ *
+ * **With Options**
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/active-record/request';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * **With an Identifier**
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/active-record/request';
+ *
+ * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method findRecord
+ * @public
+ * @static
+ * @for @ember-data/active-record/request
+ * @param identifier
+ * @param options
+ */
 export function findRecord(
   identifier: RemotelyAccessibleIdentifier,
   options?: FindRecordOptions

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

@@ -1,3 +1,6 @@
+/**
+ * @module @ember-data/active-record/request
+ */
 import { underscore } from '@ember/string';
 
 import { pluralize } from 'ember-inflector';
@@ -7,6 +10,56 @@ import type { ConstrainedRequestOptions, QueryRequestOptions } from '@ember-data
 
 import { copyForwardUrlOptions, extractCacheOptions } from './-utils';
 
+/**
+ * Builds request options to query for resources, usually by a primary
+ * type, configured for the url and header expectations of most ActiveRecord APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { query } from '@ember-data/active-record/request';
+ *
+ * const data = await store.request(query('person'));
+ * ```
+ *
+ * **With Query Params**
+ *
+ * ```ts
+ * import { query } from '@ember-data/active-record/request';
+ *
+ * const options = query('person', { include: ['pets', 'friends'] });
+ * 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 { query } from '@ember-data/active-record/request';
+ *
+ * const options = query('person', { include: ['pets', 'friends'] }, { reload: true });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method query
+ * @public
+ * @static
+ * @for @ember-data/active-record/request
+ * @param identifier
+ * @param query
+ * @param options
+ */
 export function query(
   type: string,
   // eslint-disable-next-line @typescript-eslint/no-shadow

packages/active-record/src/request.ts

@@ -1,3 +1,66 @@
+/**
+ * <p align="center">
+  <img
+    class="project-logo"
+    src="https://github.com/emberjs/data/4612c9354e4c54d53327ec2cf21955075ce21294/ember-data-logo-light.svg#gh-light-mode-only"
+    alt="EmberData"
+    width="240px"
+    title="EmberData"
+  />
+</p>
+
+This package provides utilities for working with [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html#convention-over-configuration-in-active-record) APIs with [*Ember***Data**](https://github.com/emberjs/data/).
+
+## Installation
+
+Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)
+
+```no-highlight
+pnpm add @ember-data/active-record
+```
+
+## Usage
+
+Request builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+They take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.
+
+For instance, to fetch a resource from your API
+
+```ts
+import { findRecord } from '@ember-data/active-record/request';
+
+const options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] });
+
+/\*
+  => {
+    url: 'https://api.example.com/v1/ember_developers/1?include=friends,pets',
+    method: 'GET',
+    headers: <Headers>, // 'Content-Type': 'application/json; charset=utf-8'
+    op: 'findRecord';
+    records: [{ type: 'ember-developer', id: '1' }]
+  }
+*\/
+```
+
+Request builder output may be used with either `requestManager.request` or `store.request`.
+
+URLs are stable. The same query will produce the same URL every time, even if the order of keys in
+the query or values in an array changes.
+
+URLs follow the most common ActiveRecord format (underscored pluralized resource types).
+
+### Available Builders
+
+- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/createRecord)
+- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/deleteRecord)
+- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/findRecord)
+- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/query)
+- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Factive-record/updateRecord)
+
+ *
+ * @module @ember-data/active-record/request
+ * @main @ember-data/active-record/request
+ */
 export { findRecord } from './-private/builders/find-record';
 export { query } from './-private/builders/query';
 export { deleteRecord, createRecord, updateRecord } from './-private/builders/save-record';

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

@@ -1,3 +1,6 @@
+/**
+ * @module @ember-data/json-api/request
+ */
 import { pluralize } from 'ember-inflector';
 
 import { buildBaseURL, buildQueryParams, type FindRecordUrlOptions } from '@ember-data/request-utils';
@@ -9,6 +12,43 @@ import type {
 
 import { copyForwardUrlOptions, extractCacheOptions } from './-utils';
 
+/**
+ * Builds request options to fetch a single resource by a known id or identifier
+ * configured for the url and header expectations of most JSON:API APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/json-api/request';
+ *
+ * const data = await store.request(findRecord('person', '1'));
+ * ```
+ *
+ * **With Options**
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/json-api/request';
+ *
+ * const options = findRecord('person', '1', { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * **With an Identifier**
+ *
+ * ```ts
+ * import { findRecord } from '@ember-data/json-api/request';
+ *
+ * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method findRecord
+ * @public
+ * @static
+ * @for @ember-data/json-api/request
+ * @param identifier
+ * @param options
+ */
 export function findRecord(
   identifier: RemotelyAccessibleIdentifier,
   options?: FindRecordOptions

packages/json-api/src/-private/builders/query.ts

@@ -1,10 +1,63 @@
+/**
+ * @module @ember-data/json-api/request
+ */
 import { pluralize } from 'ember-inflector';
 
 import { buildBaseURL, buildQueryParams, QueryParamsSource, type QueryUrlOptions } from '@ember-data/request-utils';
 import type { ConstrainedRequestOptions, QueryRequestOptions } from '@ember-data/types/request';
 
 import { copyForwardUrlOptions, extractCacheOptions } from './-utils';
 
+/**
+ * Builds request options to query for resources, usually by a primary
+ * type, configured for the url and header expectations of most JSON:API APIs.
+ *
+ * **Basic Usage**
+ *
+ * ```ts
+ * import { query } from '@ember-data/json-api/request';
+ *
+ * const data = await store.request(query('person'));
+ * ```
+ *
+ * **With Query Params**
+ *
+ * ```ts
+ * import { query } from '@ember-data/json-api/request';
+ *
+ * const options = query('person', { include: ['pets', 'friends'] });
+ * 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 { query } from '@ember-data/json-api/request';
+ *
+ * const options = query('person', { include: ['pets', 'friends'] }, { reload: true });
+ * const data = await store.request(options);
+ * ```
+ *
+ * @method query
+ * @public
+ * @static
+ * @for @ember-data/json-api/request
+ * @param identifier
+ * @param query
+ * @param options
+ */
 export function query(
   type: string,
   // eslint-disable-next-line @typescript-eslint/no-shadow

packages/json-api/src/request.ts

@@ -1,9 +1,28 @@
 /**
- * # Request builders and serialization utils for JSON:API requests
- *
- * ## Request Builders
+ * <p align="center">
+  <img
+    class="project-logo"
+    src="https://github.com/emberjs/data/4612c9354e4c54d53327ec2cf21955075ce21294/ember-data-logo-light.svg#gh-light-mode-only"
+    alt="EmberData"
+    width="240px"
+    title="EmberData"
+  />
+</p>
+
+This package provides utilities for working with [JSON:API](https://json-api.org) APIs with [*Ember***Data**](https://github.com/emberjs/data/).
+
+## Installation
+
+Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)
+
+```no-highlight
+pnpm add @ember-data/json-api
+```
+
+## Usage
 
-Request builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). They take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.
+Request builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+They take a few contextual inputs about the request you want to make, abstracting away the gnarlier details.
 
 For instance, to fetch a resource from your API
 
@@ -31,6 +50,15 @@ URLs are stable. The same query will produce the same URL every time, even if th
 the query or values in an array changes.
 
 URLs follow the most common JSON:API format (dasherized pluralized resource types).
+
+### Available Builders
+
+- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/createRecord)
+- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/deleteRecord)
+- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/findRecord)
+- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/query)
+- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Fjson-api/updateRecord)
+
  *
  * @module @ember-data/json-api/request
  * @main @ember-data/json-api/request