From 52f49736b6f37a9fef0bf269883f622aa4401d54 Mon Sep 17 00:00:00 2001
From: griest024 <griest024@gmail.com>
Date: Tue, 7 Jan 2025 16:00:23 -0500
Subject: [PATCH] docs(all): tag examples with `@example` (#3391)

---
 libs/analytics/src/lib/analytics-tracker.ts               | 4 ++--
 .../src/injection-tokens/unauthenticated/hooks.token.ts   | 5 +++--
 libs/auth/state/src/reducers/token/extra.token.ts         | 1 +
 libs/authorizenet/state/src/reducers/token/extra.token.ts | 1 +
 .../state/src/reducers/token/extra.token.ts               | 1 +
 .../src/injection-tokens/extra-attributes-hook.token.ts   | 8 ++++----
 .../src/injection-tokens/transforms/cart-item/token.ts    | 1 +
 .../magento/src/injection-tokens/transforms/cart/token.ts | 1 +
 libs/cart/state/src/reducers/token/extra.token.ts         | 1 +
 libs/cart/state/src/reducers/token/meta.token.ts          | 1 +
 libs/category/driver/magento/src/fragments/token.ts       | 1 +
 libs/category/driver/magento/src/transforms/token.ts      | 1 +
 .../src/injection-tokens/request/builders.token.ts        | 1 +
 libs/category/state/src/reducers/token/extra.token.ts     | 1 +
 libs/core/external-script/src/external-script.service.ts  | 2 +-
 libs/core/external-script/src/script.ts                   | 3 +--
 .../testing/src/external-script.service.ts                | 5 +----
 libs/core/src/constructable/constructable.ts              | 2 +-
 libs/core/testing/src/factories/factory.ts                | 4 +---
 .../2-4-5/src/injection-tokens/fragments/order.token.ts   | 1 +
 .../2-4-5/src/injection-tokens/transforms/extra.token.ts  | 1 +
 .../2-4-6/src/injection-tokens/fragments/order.token.ts   | 1 +
 .../2-4-6/src/injection-tokens/transforms/extra.token.ts  | 1 +
 .../state/src/reducers/token/extra.token.ts               | 1 +
 .../state/src/reducers/token/extra.token.ts               | 1 +
 libs/customer/state/src/reducers/token/extra.token.ts     | 1 +
 .../driver/magento/2.4.1/src/magento.module.ts            | 1 +
 .../driver/magento/2.4.2/src/magento.module.ts            | 1 +
 .../driver/magento/2.4.3/src/magento.module.ts            | 1 +
 libs/external-router/src/model/resolvable-route.ts        | 1 +
 libs/navigation/driver/magento/src/transforms/token.ts    | 1 +
 libs/order/state/src/reducers/token/extra.token.ts        | 1 +
 libs/payment/state/src/reducers/token/extra.token.ts      | 1 +
 .../testing/src/injection-tokens/factories/kind.token.ts  | 1 +
 .../state/src/reducers/injection-tokens/extra.token.ts    | 1 +
 .../state/src/reducers/injection-tokens/extra.token.ts    | 1 +
 .../transforms/product-response/response-extra.token.ts   | 1 +
 .../src/injection-tokens/fragments/product-page.token.ts  | 1 +
 .../injection-tokens/fragments/product-preview.token.ts   | 1 +
 .../src/injection-tokens/fragments/product.token.ts       | 1 +
 .../transforms/product-preview/preview-extra.token.ts     | 1 +
 .../transforms/product-response/response-extra.token.ts   | 1 +
 .../injection-tokens/transforms/product/extra.token.ts    | 1 +
 .../state/src/reducers/injection-tokens/extra.token.ts    | 1 +
 .../state/src/reducers/injection-tokens/meta.token.ts     | 1 +
 .../testing/src/injection-tokens/factories/extra.token.ts | 1 +
 .../testing/src/injection-tokens/factories/type.token.ts  | 1 +
 .../state/src/reducers/injection-tokens/extra.token.ts    | 1 +
 .../state/src/reducers/injection-tokens/meta.token.ts     | 1 +
 .../federated/src/injection-tokens/drivers.token.ts       | 1 +
 .../in-memory/src/injection-tokens/backends.token.ts      | 1 +
 .../src/injection-tokens/search-options/builders.token.ts | 1 +
 libs/search/state/src/reducers/token/extra.token.ts       | 1 +
 .../testing/src/injection-tokens/factories/kind.token.ts  | 1 +
 libs/seo/router/src/canonical/updates.token.ts            | 1 +
 libs/seo/router/src/meta/updates.token.ts                 | 1 +
 libs/seo/router/src/providers/canonical-provider.ts       | 4 ++--
 libs/seo/router/src/providers/meta-provider.ts            | 3 +--
 libs/seo/router/src/providers/title-provider.ts           | 3 +--
 libs/seo/router/src/title/updates.token.ts                | 1 +
 .../state/src/injection-tokens/canonical/updates.token.ts | 1 +
 libs/seo/state/src/injection-tokens/meta/updates.token.ts | 1 +
 .../seo/state/src/injection-tokens/title/updates.token.ts | 1 +
 tools/jasmine/src/idempotence.ts                          | 5 +++--
 64 files changed, 73 insertions(+), 27 deletions(-)

diff --git a/libs/analytics/src/lib/analytics-tracker.ts b/libs/analytics/src/lib/analytics-tracker.ts
index 4100be8020..ad8550dae9 100644
--- 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
index f8bd2c5d2a..d373525653 100644
--- 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
index 91909aef51..25e4bb7753 100644
--- 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
index d79497372a..de1cc479f7 100644
--- 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
index 9f47e1016c..bcc600f491 100644
--- 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
index 0f43b9b6c6..feda90f599 100644
--- 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
index bdd64ba5df..4a90a8538f 100644
--- 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
index 8950f513a6..90fda70962 100644
--- 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
index a3ac6f6a77..94014d2674 100644
--- 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
index 2be5992a4d..43c1e3d8e9 100644
--- 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
index db7e3d1b98..033c6e88f2 100644
--- 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
index 018d14226f..2ca8b1a3e4 100644
--- 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
index b5bc01abf4..6b46bdbb2d 100644
--- 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
index b148f52779..7cdf8141c0 100644
--- 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
index 24045d8f9b..79f3e808c2 100644
--- 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
index 320003d0d4..8ef21ce5ed 100644
--- 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
index e191cb3c49..516110ed21 100644
--- 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
index 4448fa9b0f..d7079f48f9 100644
--- 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
index 0b7c90780a..82688ff28a 100644
--- 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
index 1f82e96ba5..db9537ebf9 100644
--- 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
index 9252232783..48d5c3c2d1 100644
--- 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
index b113a463d9..7e742515b6 100644
--- 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
index 1020325d7c..f7704f0f9d 100644
--- 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
index c252fd83ce..709b8cf5d1 100644
--- 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
index 19f859d65c..ecc8650e73 100644
--- 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
index f3c05b8b87..a18940466e 100644
--- 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
index f34f4adfc3..51db157058 100644
--- 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
index b6e490364c..b947e5f049 100644
--- 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
index 29c52f3958..acc4285d74 100644
--- 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
index 421766f8bc..051e883afc 100644
--- 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
index aef98f9e9b..4a0deecc5d 100644
--- 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
index 06778ccd10..a2b3ae57ce 100644
--- 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
index d4f3bd038e..6b98c5b85a 100644
--- 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
index 2b393449fe..9d64fe6b1a 100644
--- 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
index 7f843b3be7..f30cfb88a3 100644
--- 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
index 0b991d2df6..3244d56327 100644
--- 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/libs/product/driver/in-memory/src/injection-tokens/transforms/product-response/response-extra.token.ts b/libs/product/driver/in-memory/src/injection-tokens/transforms/product-response/response-extra.token.ts
index c6da79d837..b217a3a08a 100644
--- a/libs/product/driver/in-memory/src/injection-tokens/transforms/product-response/response-extra.token.ts
+++ b/libs/product/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
index 9f8d61373a..3043c0e69e 100644
--- 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
index df48ebd776..18a871e26a 100644
--- 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
index 6c9c3bd749..6e64e8b2b7 100644
--- 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/libs/product/driver/magento/src/injection-tokens/transforms/product-preview/preview-extra.token.ts b/libs/product/driver/magento/src/injection-tokens/transforms/product-preview/preview-extra.token.ts
index c137fd374b..9cb33c8a05 100644
--- a/libs/product/driver/magento/src/injection-tokens/transforms/product-preview/preview-extra.token.ts
+++ b/libs/product/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/libs/product/driver/magento/src/injection-tokens/transforms/product-response/response-extra.token.ts b/libs/product/driver/magento/src/injection-tokens/transforms/product-response/response-extra.token.ts
index 97626fd263..2ead8b58c9 100644
--- a/libs/product/driver/magento/src/injection-tokens/transforms/product-response/response-extra.token.ts
+++ b/libs/product/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
index 0ec97f6765..24160f28c3 100644
--- 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
index 08fe1e2bf9..a029db2f1c 100644
--- 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(
diff --git a/libs/product/state/src/reducers/injection-tokens/meta.token.ts b/libs/product/state/src/reducers/injection-tokens/meta.token.ts
index 0c23773532..66998267fd 100644
--- a/libs/product/state/src/reducers/injection-tokens/meta.token.ts
+++ b/libs/product/state/src/reducers/injection-tokens/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: [
    *   ...daffProductProvideMetaReducers(
diff --git a/libs/product/testing/src/injection-tokens/factories/extra.token.ts b/libs/product/testing/src/injection-tokens/factories/extra.token.ts
index 25ee71ff91..ef225a3ea3 100644
--- a/libs/product/testing/src/injection-tokens/factories/extra.token.ts
+++ b/libs/product/testing/src/injection-tokens/factories/extra.token.ts
@@ -18,6 +18,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_EXTRA_FACTORIES}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductExtraProductFactories(
diff --git a/libs/product/testing/src/injection-tokens/factories/type.token.ts b/libs/product/testing/src/injection-tokens/factories/type.token.ts
index 25cbb4de6e..1c26923994 100644
--- a/libs/product/testing/src/injection-tokens/factories/type.token.ts
+++ b/libs/product/testing/src/injection-tokens/factories/type.token.ts
@@ -16,6 +16,7 @@ export const {
    *
    * See {@link DAFF_PRODUCT_TYPE_FACTORIES}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffProductExtraFactoryTypes(
diff --git a/libs/reviews/state/src/reducers/injection-tokens/extra.token.ts b/libs/reviews/state/src/reducers/injection-tokens/extra.token.ts
index 86990caafb..a4bb6b733e 100644
--- a/libs/reviews/state/src/reducers/injection-tokens/extra.token.ts
+++ b/libs/reviews/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: [
    *   ...daffReviewsProvideExtraReducers(
diff --git a/libs/reviews/state/src/reducers/injection-tokens/meta.token.ts b/libs/reviews/state/src/reducers/injection-tokens/meta.token.ts
index f82b6388db..7d0058f8ad 100644
--- a/libs/reviews/state/src/reducers/injection-tokens/meta.token.ts
+++ b/libs/reviews/state/src/reducers/injection-tokens/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: [
    *   ...daffReviewsProvideMetaReducers(
diff --git a/libs/search/driver/federated/src/injection-tokens/drivers.token.ts b/libs/search/driver/federated/src/injection-tokens/drivers.token.ts
index 34bba4848e..83869e0f7d 100644
--- a/libs/search/driver/federated/src/injection-tokens/drivers.token.ts
+++ b/libs/search/driver/federated/src/injection-tokens/drivers.token.ts
@@ -15,6 +15,7 @@ export const {
    *
    * See {@link DAFF_SEARCH_FEDERATED_DRIVERS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffSearchFederatedDrivers(MySearchDriver)
diff --git a/libs/search/driver/in-memory/src/injection-tokens/backends.token.ts b/libs/search/driver/in-memory/src/injection-tokens/backends.token.ts
index 63c1f5effd..df2561874c 100644
--- a/libs/search/driver/in-memory/src/injection-tokens/backends.token.ts
+++ b/libs/search/driver/in-memory/src/injection-tokens/backends.token.ts
@@ -15,6 +15,7 @@ export const {
    *
    * See {@link DAFF_SEARCH_IN_MEMORY_BACKENDS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffSearchInMemoryBackends(MySearchFeatureBackend)
diff --git a/libs/search/routing/src/injection-tokens/search-options/builders.token.ts b/libs/search/routing/src/injection-tokens/search-options/builders.token.ts
index a24fcb6eeb..ca1485cffb 100644
--- a/libs/search/routing/src/injection-tokens/search-options/builders.token.ts
+++ b/libs/search/routing/src/injection-tokens/search-options/builders.token.ts
@@ -18,6 +18,7 @@ export const {
    *
    * See {@link DAFF_SEARCH_ROUTING_OPTIONS_BUILDERS}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffSearchRoutingOptionBuilders(
diff --git a/libs/search/state/src/reducers/token/extra.token.ts b/libs/search/state/src/reducers/token/extra.token.ts
index 78f3e90284..58292052d6 100644
--- a/libs/search/state/src/reducers/token/extra.token.ts
+++ b/libs/search/state/src/reducers/token/extra.token.ts
@@ -16,6 +16,7 @@ export const {
   /**
    * Provides additional reducers that run after the standard Daffodil cart reducers.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...daffSearchProvideExtraReducers(
diff --git a/libs/search/testing/src/injection-tokens/factories/kind.token.ts b/libs/search/testing/src/injection-tokens/factories/kind.token.ts
index 34f5105b9a..1c8df2debb 100644
--- a/libs/search/testing/src/injection-tokens/factories/kind.token.ts
+++ b/libs/search/testing/src/injection-tokens/factories/kind.token.ts
@@ -20,6 +20,7 @@ export const {
    *
    * See {@link DAFF_SEARCH_RESULT_KIND_FACTORIES}.
    *
+   * @example
    * ```ts
    * providers: [
    *   ...provideDaffSearchResultKindFactories(
diff --git a/libs/seo/router/src/canonical/updates.token.ts b/libs/seo/router/src/canonical/updates.token.ts
index 51b707e6a2..b8814c3606 100644
--- a/libs/seo/router/src/canonical/updates.token.ts
+++ b/libs/seo/router/src/canonical/updates.token.ts
@@ -20,6 +20,7 @@ const {
  *
  * See {@link DAFF_SEO_CANONICAL_URL_ROUTER_UPDATES}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffCanonicalUrlUpdates(
diff --git a/libs/seo/router/src/meta/updates.token.ts b/libs/seo/router/src/meta/updates.token.ts
index 4fda5e0af4..fb174de621 100644
--- a/libs/seo/router/src/meta/updates.token.ts
+++ b/libs/seo/router/src/meta/updates.token.ts
@@ -20,6 +20,7 @@ const {
  *
  * See {@link DAFF_SEO_META_ROUTER_UPDATES}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffMetaUpdates(
diff --git a/libs/seo/router/src/providers/canonical-provider.ts b/libs/seo/router/src/providers/canonical-provider.ts
index a4ca02c337..c28f6219c1 100644
--- a/libs/seo/router/src/providers/canonical-provider.ts
+++ b/libs/seo/router/src/providers/canonical-provider.ts
@@ -12,8 +12,7 @@ import { DaffSeoNativeCanonicalUrlEffects } from '../effects/canonical.effects';
  *
  * This provider is intended to only be imported exactly once in the root of the application.
  *
- * ## Usage
- *
+ * @example
  * ```ts
  * @NgModule({
  *   providers: [
@@ -23,6 +22,7 @@ import { DaffSeoNativeCanonicalUrlEffects } from '../effects/canonical.effects';
  * export class AppModule { }
  * ```
  */
+// TODO: change return type to EnvironmentProvider
 export const daffSeoRouterCanonicalProvider = (): Provider[] => [
   DaffSeoNativeCanonicalUrlEffects,
   {
diff --git a/libs/seo/router/src/providers/meta-provider.ts b/libs/seo/router/src/providers/meta-provider.ts
index 870898879d..f628fd293b 100644
--- a/libs/seo/router/src/providers/meta-provider.ts
+++ b/libs/seo/router/src/providers/meta-provider.ts
@@ -11,8 +11,7 @@ import { DaffSeoNativeMetaEffects } from '../effects/meta.effects';
  *
  * This provider is intended to only be imported exactly once in the root of the application.
  *
- * ## Usage
- *
+ * @example
  * ```ts
  * @NgModule({
  *   providers: [
diff --git a/libs/seo/router/src/providers/title-provider.ts b/libs/seo/router/src/providers/title-provider.ts
index 4a9a308c69..77dac83805 100644
--- a/libs/seo/router/src/providers/title-provider.ts
+++ b/libs/seo/router/src/providers/title-provider.ts
@@ -13,8 +13,7 @@ import { DaffSeoNativeTitleEffects } from '../effects/title.effects';
  *
  * @deprecated since Angular 14. See https://angular.io/api/router/TitleStrategy Deprecated in version 0.78.0. Will be removed in version 0.81.0.
  *
- * ## Usage
- *
+ * @example
  * ```ts
  * @NgModule({
  *   providers: [
diff --git a/libs/seo/router/src/title/updates.token.ts b/libs/seo/router/src/title/updates.token.ts
index e873928289..ef4fa63140 100644
--- a/libs/seo/router/src/title/updates.token.ts
+++ b/libs/seo/router/src/title/updates.token.ts
@@ -19,6 +19,7 @@ const {
  *
  * See {@link DAFF_SEO_TITLE_ROUTER_UPDATES}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffTitleUpdates(
diff --git a/libs/seo/state/src/injection-tokens/canonical/updates.token.ts b/libs/seo/state/src/injection-tokens/canonical/updates.token.ts
index 7e5c1c49b8..37a48cd3e3 100644
--- a/libs/seo/state/src/injection-tokens/canonical/updates.token.ts
+++ b/libs/seo/state/src/injection-tokens/canonical/updates.token.ts
@@ -19,6 +19,7 @@ const {
  *
  * See {@link DAFF_SEO_CANONICAL_URL_UPDATES}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffCanonicalUrlUpdates(
diff --git a/libs/seo/state/src/injection-tokens/meta/updates.token.ts b/libs/seo/state/src/injection-tokens/meta/updates.token.ts
index 3cc37fc9c5..a47edcc971 100644
--- a/libs/seo/state/src/injection-tokens/meta/updates.token.ts
+++ b/libs/seo/state/src/injection-tokens/meta/updates.token.ts
@@ -20,6 +20,7 @@ const {
  *
  * See {@link DAFF_SEO_META_UPDATES}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffMetaUpdates(
diff --git a/libs/seo/state/src/injection-tokens/title/updates.token.ts b/libs/seo/state/src/injection-tokens/title/updates.token.ts
index 15e8adb0d8..1d1c88ddb0 100644
--- a/libs/seo/state/src/injection-tokens/title/updates.token.ts
+++ b/libs/seo/state/src/injection-tokens/title/updates.token.ts
@@ -19,6 +19,7 @@ const {
  *
  * See {@link DAFF_SEO_TITLE_UPDATES}.
  *
+ * @example
  * ```ts
  * providers: [
  *   ...provideDaffTitleUpdates(
diff --git a/tools/jasmine/src/idempotence.ts b/tools/jasmine/src/idempotence.ts
index 676d67fdb3..d07f5349ae 100644
--- a/tools/jasmine/src/idempotence.ts
+++ b/tools/jasmine/src/idempotence.ts
@@ -4,13 +4,14 @@ import MatchersUtil = jasmine.MatchersUtil;
  * A matcher for jasmine that allows you to test whether or not a function
  * is idempotent.
  *
+ * For higher arity functions, see the specs for this matcher.
+ *
+ * @example
  * ```ts
  * it('should return true if the function is idempotent', () => {
  *     expect((idempotentArg?: number) => (anArityOneIdempotentFunction(idempotentArg || 2))).toBeIdempotent();
  * });
  * ```
- *
- * For higher arity functions, see the specs for this matcher.
  */
 export const idempotenceMatcher = <T>(matchersUtil: MatchersUtil) => ({
   compare: (actual: (arg?: T) => T, expected: void) => {