docs(all): tag examples with @example (#3391)

graycoreio · Jan 7, 2025 · 52f4973 · 52f4973
1 parent 3e7404d
commit 52f4973
Show file tree

Hide file tree

Showing 64 changed files with 73 additions and 27 deletions.
diff --git a/libs/analytics/src/lib/analytics-tracker.ts b/libs/analytics/src/lib/analytics-tracker.ts
@@ -20,7 +20,7 @@ export type DaffAnalyticsTrackerFunction = (event: DaffAnalyticsEvent) => Observ
 /**
  * The tracker type.
  *
- * Trackers can either be classes:
+ * @example Implementing a tracker as a class
  *
  * ```ts
  * export class MyTracker implements DaffAnalyticsTracker {
@@ -30,7 +30,7 @@ export type DaffAnalyticsTrackerFunction = (event: DaffAnalyticsEvent) => Observ
  * }
  * ```
  *
- * or functions:
+ * @example Implementing a tracker as a function
  *
  * ```ts
  * export const trackThis = (event: DaffAnalyticsEvent) => {

diff --git a/libs/auth/state/src/injection-tokens/unauthenticated/hooks.token.ts b/libs/auth/state/src/injection-tokens/unauthenticated/hooks.token.ts
@@ -13,11 +13,12 @@ export const {
   /**
    * Provides {@link DAFF_AUTH_UNAUTHENTICATED_HOOKS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffAuthProvideUnauthenticatedHooks(
-   *     myReducer1,
-   *     myReducer2
+   *     myHook1,
+   *     myHook2
    *   )
    * ]
    * ```

diff --git a/libs/auth/state/src/reducers/token/extra.token.ts b/libs/auth/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil auth reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffAuthProvideExtraReducers(

diff --git a/libs/authorizenet/state/src/reducers/token/extra.token.ts b/libs/authorizenet/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil authorizenet reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffAuthorizeNetProvideExtraReducers(

diff --git a/libs/cart-store-credit/state/src/reducers/token/extra.token.ts b/libs/cart-store-credit/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCartStoreCreditProvideExtraReducers(

diff --git a/libs/cart/driver/in-memory/src/injection-tokens/extra-attributes-hook.token.ts b/libs/cart/driver/in-memory/src/injection-tokens/extra-attributes-hook.token.ts
@@ -14,15 +14,15 @@ export const {
    * The value returned by the hook function will be set to the returned cart's `extra_attributes` field
    * for driver calls that return a cart.
    *
-   * The following example demonstrates adding the `numberOfCartItems` field to `extra_attributes`:
+   * Note that this and any `extra_attributes` features are for advanced users
+   * and should be used with care.
+   *
+   * @example Adding the `numberOfCartItems` field to `extra_attributes`
    * ```ts
    * (reqInfo: RequestInfo, cart: DaffCart) => ({
    *   numberOfCartItems: cart.items.length
    * })
    * ```
-   *
-   * Note that this and any `extra_attributes` features are for advanced users
-   * and should be used with care.
    */
   token: DAFF_CART_IN_MEMORY_EXTRA_ATTRIBUTES_HOOK,
   /**

diff --git a/libs/cart/driver/magento/src/injection-tokens/transforms/cart-item/token.ts b/libs/cart/driver/magento/src/injection-tokens/transforms/cart-item/token.ts
@@ -16,6 +16,7 @@ export const {
    *
    * See {@link DAFF_CART_MAGENTO_CART_ITEM_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffCartMagentoCartItemTransforms(

diff --git a/libs/cart/driver/magento/src/injection-tokens/transforms/cart/token.ts b/libs/cart/driver/magento/src/injection-tokens/transforms/cart/token.ts
@@ -20,6 +20,7 @@ export const {
    *
    * See {@link DAFF_CART_MAGENTO_CART_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffCartMagentoCartTransforms(

diff --git a/libs/cart/state/src/reducers/token/extra.token.ts b/libs/cart/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCartProvideExtraReducers(

diff --git a/libs/cart/state/src/reducers/token/meta.token.ts b/libs/cart/state/src/reducers/token/meta.token.ts
@@ -16,6 +16,7 @@ export const {
   /**
    * Provides additional meta-reducers that run after the standard Daffodil cart meta-reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCartProvideMetaReducers(

diff --git a/libs/category/driver/magento/src/fragments/token.ts b/libs/category/driver/magento/src/fragments/token.ts
@@ -14,6 +14,7 @@ export const {
    *
    * See {@link MAGENTO_CATEGORY_EXTRA_FRAGMENTS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...magentoProvideCategoryExtraFragments(

diff --git a/libs/category/driver/magento/src/transforms/token.ts b/libs/category/driver/magento/src/transforms/token.ts
@@ -15,6 +15,7 @@ export const {
    *
    * See {@link MAGENTO_CATEGORY_EXTRA_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...magentoProvideCategoryExtraTransforms(

diff --git a/libs/category/routing/src/injection-tokens/request/builders.token.ts b/libs/category/routing/src/injection-tokens/request/builders.token.ts
@@ -20,6 +20,7 @@ export const {
    *
    * See {@link DAFF_CATEGORY_ROUTING_OPTIONS_BUILDERS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffCategoryRoutingRequestBuilders(

diff --git a/libs/category/state/src/reducers/token/extra.token.ts b/libs/category/state/src/reducers/token/extra.token.ts
@@ -14,6 +14,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil category reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCategoryProvideExtraReducers(

diff --git a/libs/core/external-script/src/external-script.service.ts b/libs/core/external-script/src/external-script.service.ts
@@ -24,7 +24,7 @@ export interface LoadedExternalScript extends DaffExternalScript {
  *
  * ### Usage example
  *
- * The following loads an external script into the document.
+ * @example Loading an external script into the document
  *
  * ```ts
  * import { DOCUMENT } from '@angular/common';

diff --git a/libs/core/external-script/src/script.ts b/libs/core/external-script/src/script.ts
@@ -1,9 +1,8 @@
 /**
  * Represents the structure of an external script that can be loaded into a document.
  *
+ * @example Using DaffExternalScript interface to define an external script object
  * ```ts
- * // Example of using DaffExternalScript interface to define an external script object.
- *
  * const externalScript: DaffExternalScript = {
  *  src: 'https://example.com/script.js',
  *  async: true,

diff --git a/libs/core/external-script/testing/src/external-script.service.ts b/libs/core/external-script/testing/src/external-script.service.ts
@@ -13,12 +13,9 @@ import { TestScripts } from './constants';
 /**
  * A service for loading external scripts into the document.
  *
- * ### Usage example
- *
- * The following loads an external script into the document.
+ * @example Loading an external script into the document
  *
  * ```ts
- *
  * import { DaffExternalScriptTestingService } from '@daffodil/core/external-script/testing';
  *
  * const externalScriptService = new DaffExternalScriptTestingService();

diff --git a/libs/core/src/constructable/constructable.ts b/libs/core/src/constructable/constructable.ts
@@ -2,7 +2,7 @@
  * A type which describes a function which would return an instance of a class
  * Typically, we call this the "new" method in a language.
  *
- * A sample usage:
+ * @example
  * ```ts
  * class MyClass {
  *  readonly myProp: string = 'prop';

diff --git a/libs/core/testing/src/factories/factory.ts b/libs/core/testing/src/factories/factory.ts
@@ -13,9 +13,7 @@ import { IDaffModelFactory } from './factory.interface';
  *
  * The constructor args can be omitted if the `create` method is overridden.
  *
- * The following example demonstrates using this feature to inject
- * a different factory into a mock class.
- *
+ * @example Injecting a different factory into a mock class
  * ```ts
  * class MyMockModel {
  *  constructor(

diff --git a/libs/customer-order/driver/magento/2-4-5/src/injection-tokens/fragments/order.token.ts b/libs/customer-order/driver/magento/2-4-5/src/injection-tokens/fragments/order.token.ts
@@ -21,6 +21,7 @@ export const {
    *
    * See {@link DAFF_CUSTOMER_ORDER_MAGENTO_EXTRA_ORDER_FRAGMENTS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffCustomerOrderMagentoExtraOrderFragments(

diff --git a/libs/customer-order/driver/magento/2-4-5/src/injection-tokens/transforms/extra.token.ts b/libs/customer-order/driver/magento/2-4-5/src/injection-tokens/transforms/extra.token.ts
@@ -19,6 +19,7 @@ export const {
    *
    * See {@link DAFF_CUSTOMER_ORDER_MAGENTO_EXTRA_ORDER_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffCustomerOrderMagentoExtraOrderTransforms(

diff --git a/libs/customer-order/driver/magento/2-4-6/src/injection-tokens/fragments/order.token.ts b/libs/customer-order/driver/magento/2-4-6/src/injection-tokens/fragments/order.token.ts
@@ -24,6 +24,7 @@ const {
  *
  * See {@link DAFF_CUSTOMER_ORDER_MAGENTO_EXTRA_ORDER_FRAGMENTS}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffCustomerOrderMagentoExtraOrderFragments(

diff --git a/libs/customer-order/driver/magento/2-4-6/src/injection-tokens/transforms/extra.token.ts b/libs/customer-order/driver/magento/2-4-6/src/injection-tokens/transforms/extra.token.ts
@@ -23,6 +23,7 @@ const {
  *
  * See {@link DAFF_CUSTOMER_ORDER_MAGENTO_EXTRA_ORDER_TRANSFORMS}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffCustomerOrderMagentoExtraOrderTransforms(

diff --git a/libs/customer-payment/state/src/reducers/token/extra.token.ts b/libs/customer-payment/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil customer reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCustomerPaymentProvideExtraReducers(

diff --git a/libs/customer-store-credit/state/src/reducers/token/extra.token.ts b/libs/customer-store-credit/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil customer reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCustomerStoreCreditProvideExtraReducers(

diff --git a/libs/customer/state/src/reducers/token/extra.token.ts b/libs/customer/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil customer reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffCustomerProvideExtraReducers(

diff --git a/libs/external-router/driver/magento/2.4.1/src/magento.module.ts b/libs/external-router/driver/magento/2.4.1/src/magento.module.ts
@@ -12,6 +12,7 @@ import { DaffExternalRouterMagentoDriver } from './magento.service';
 /**
  * The module used to configure the {@link DaffExternalRouterDriver} for usage with Magento.
  *
+ * @example
  * ```ts
  * @NgModule({
  *   declarations: [],

diff --git a/libs/external-router/driver/magento/2.4.2/src/magento.module.ts b/libs/external-router/driver/magento/2.4.2/src/magento.module.ts
@@ -13,6 +13,7 @@ import { DaffExternalRouterMagentoDriver } from './magento.service';
 /**
  * The module used to configure the {@link DaffExternalRouterDriver} for usage with Magento.
  *
+ * @example
  * ```ts
  * @NgModule({
  *   declarations: [],

diff --git a/libs/external-router/driver/magento/2.4.3/src/magento.module.ts b/libs/external-router/driver/magento/2.4.3/src/magento.module.ts
@@ -13,6 +13,7 @@ import { DaffExternalRouterMagentoDriver } from './magento.service';
 /**
  * The module used to configure the {@link DaffExternalRouterDriver} for usage with Magento.
  *
+ * @example
  * ```ts
  * @NgModule({
  *   declarations: [],

diff --git a/libs/external-router/src/model/resolvable-route.ts b/libs/external-router/src/model/resolvable-route.ts
@@ -7,6 +7,7 @@ import { DaffExternalRouteType } from './route-type';
  * A `DaffExternallyResolvableUrl` describes the relationship between a "type" of route
  * as determined by an external platform and a URI.
  *
+ * @example
  * ```ts
  * export const resolvableRoute: DaffExternallyResolvableUrl = {
  *  id: "id-of-resource",

diff --git a/libs/navigation/driver/magento/src/transforms/token.ts b/libs/navigation/driver/magento/src/transforms/token.ts
@@ -15,6 +15,7 @@ export const {
    *
    * See {@link MAGENTO_NAVIGATION_TREE_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...magentoProvideNavigationTreeTransforms(

diff --git a/libs/order/state/src/reducers/token/extra.token.ts b/libs/order/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil order reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffOrderProvideExtraReducers(

diff --git a/libs/payment/state/src/reducers/token/extra.token.ts b/libs/payment/state/src/reducers/token/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffPaymentProvideExtraReducers(

diff --git a/libs/payment/testing/src/injection-tokens/factories/kind.token.ts b/libs/payment/testing/src/injection-tokens/factories/kind.token.ts
@@ -20,6 +20,7 @@ export const {
    *
    * See {@link DAFF_PAYMENT_RESPONSE_KIND_FACTORIES}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffPaymentResponseKindFactories(

diff --git a/libs/product-composite/state/src/reducers/injection-tokens/extra.token.ts b/libs/product-composite/state/src/reducers/injection-tokens/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffProductCompositeProvideExtraReducers(

diff --git a/libs/product-configurable/state/src/reducers/injection-tokens/extra.token.ts b/libs/product-configurable/state/src/reducers/injection-tokens/extra.token.ts
@@ -15,6 +15,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffProductConfigurableProvideExtraReducers(

diff --git a/...driver/in-memory/src/injection-tokens/transforms/product-response/response-extra.token.ts b/...driver/in-memory/src/injection-tokens/transforms/product-response/response-extra.token.ts
@@ -17,6 +17,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_IN_MEMORY_EXTRA_PRODUCT_RESPONSE_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductInMemoryExtraProductResponseTransforms(

diff --git a/libs/product/driver/magento/src/injection-tokens/fragments/product-page.token.ts b/libs/product/driver/magento/src/injection-tokens/fragments/product-page.token.ts
@@ -21,6 +21,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_MAGENTO_EXTRA_PRODUCT_PAGE_FRAGMENTS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductMagentoExtraProductPageFragments(

diff --git a/libs/product/driver/magento/src/injection-tokens/fragments/product-preview.token.ts b/libs/product/driver/magento/src/injection-tokens/fragments/product-preview.token.ts
@@ -25,6 +25,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_MAGENTO_EXTRA_PRODUCT_PREVIEW_FRAGMENTS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductMagentoExtraProductPreviewFragments(

diff --git a/libs/product/driver/magento/src/injection-tokens/fragments/product.token.ts b/libs/product/driver/magento/src/injection-tokens/fragments/product.token.ts
@@ -21,6 +21,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_MAGENTO_EXTRA_PRODUCT_FRAGMENTS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductMagentoExtraProductFragments(

diff --git a/...uct/driver/magento/src/injection-tokens/transforms/product-preview/preview-extra.token.ts b/...uct/driver/magento/src/injection-tokens/transforms/product-preview/preview-extra.token.ts
@@ -23,6 +23,7 @@ export const {
  *
  * See {@link DAFF_PRODUCT_MAGENTO_EXTRA_PRODUCT_PREVIEW_TRANSFORMS}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffProductMagentoExtraProductPreviewTransforms(

diff --git a/...t/driver/magento/src/injection-tokens/transforms/product-response/response-extra.token.ts b/...t/driver/magento/src/injection-tokens/transforms/product-response/response-extra.token.ts
@@ -18,6 +18,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_MAGENTO_EXTRA_PRODUCT_RESPONSE_TRANSFORMS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductMagentoExtraProductResponseTransforms(

diff --git a/libs/product/driver/magento/src/injection-tokens/transforms/product/extra.token.ts b/libs/product/driver/magento/src/injection-tokens/transforms/product/extra.token.ts
@@ -23,6 +23,7 @@ export const {
  *
  * See {@link DAFF_PRODUCT_MAGENTO_EXTRA_PRODUCT_TRANSFORMS}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffProductMagentoExtraProductTransforms(

diff --git a/libs/product/state/src/reducers/injection-tokens/extra.token.ts b/libs/product/state/src/reducers/injection-tokens/extra.token.ts
@@ -16,6 +16,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffProductProvideExtraReducers(