From d37ab4903b344ee63bf7d059bc9f031a1ece29ec Mon Sep 17 00:00:00 2001
From: "Elain T." <elain.tsai@graycore.io>
Date: Fri, 10 Jan 2025 12:05:43 -0500
Subject: [PATCH] docs(design): tag examples with `@example` (#3392)

---
 .../src/button/basic/button.component.ts      |  2 +-
 .../button/src/button/flat/flat.component.ts  |  2 +-
 .../button/src/button/icon/icon.component.ts  |  2 +-
 .../src/button/raised/raised.component.ts     |  2 +-
 .../src/button/stroked/stroked.component.ts   |  2 +-
 .../button/underline/underline.component.ts   |  2 +-
 .../sidebar-viewport.component.ts             | 24 +++++-----
 .../article-encapsulated.directive.ts         |  9 ++--
 .../src/core/colorable/colorable.directive.ts | 46 +++++++++++--------
 .../core/compactable/compactable.directive.ts | 16 +++----
 libs/design/src/core/focus/stack.service.ts   |  4 +-
 .../manage-container-layout.directive.ts      |  6 +--
 .../src/core/openable/openable.directive.ts   |  3 +-
 .../src/core/sizable/sizable.directive.ts     | 12 ++---
 .../skeletonable/skeletonable.directive.ts    | 16 +++----
 .../core/statusable/statusable.directive.ts   | 12 ++---
 .../text-alignable.directive.ts               | 21 ++++-----
 .../switch/src/switch/switch.component.ts     |  7 ++-
 .../src/tabs/tab-label/tab-label.component.ts |  1 +
 .../src/tabs/tab-panel/tab-panel.component.ts |  1 +
 .../design/tabs/src/tabs/tab/tab.component.ts |  5 +-
 libs/design/tabs/src/tabs/tabs.component.ts   |  2 +-
 .../tree/src/tree-item/tree-item.directive.ts | 11 ++---
 libs/design/tree/src/tree/tree.component.ts   |  3 +-
 24 files changed, 105 insertions(+), 106 deletions(-)

diff --git a/libs/design/button/src/button/basic/button.component.ts b/libs/design/button/src/button/basic/button.component.ts
index a0a0866446..d701aa5c64 100644
--- a/libs/design/button/src/button/basic/button.component.ts
+++ b/libs/design/button/src/button/basic/button.component.ts
@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffButtonComponent is a rectangular contained button with background color.
  *
- * ## Usage
+ * @example Basic button
  * ```html
  * <button daff-button>
  *  <div daffPrefix></div>
diff --git a/libs/design/button/src/button/flat/flat.component.ts b/libs/design/button/src/button/flat/flat.component.ts
index 3bf64977c8..3f0741593e 100644
--- a/libs/design/button/src/button/flat/flat.component.ts
+++ b/libs/design/button/src/button/flat/flat.component.ts
@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffFlatButtonComponent is a rectangular contained button no background.
  *
- * ## Usage
+ * @example Flat button
  * ```html
  * <button daff-flat-button>
  *  <div daffPrefix></div>
diff --git a/libs/design/button/src/button/icon/icon.component.ts b/libs/design/button/src/button/icon/icon.component.ts
index 914ae1cbe4..c42054de9d 100644
--- a/libs/design/button/src/button/icon/icon.component.ts
+++ b/libs/design/button/src/button/icon/icon.component.ts
@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffIconButtonComponent is an icon button used with icon fonts.
  *
- * ## Usage
+ * @example Icon button
  * ```html
  * <button daff-icon-button>
  *  <fa-icon [icon]="faPlus"></fa-icon>
diff --git a/libs/design/button/src/button/raised/raised.component.ts b/libs/design/button/src/button/raised/raised.component.ts
index ed0e924af2..de977cddbc 100644
--- a/libs/design/button/src/button/raised/raised.component.ts
+++ b/libs/design/button/src/button/raised/raised.component.ts
@@ -13,7 +13,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffRaisedButtonComponent is a rectangular contained button with background color and elevation.
  *
- * ## Usage
+ * @example Raised button
  * ```html
  * <button daff-raised-button>
  *  <div daffPrefix></div>
diff --git a/libs/design/button/src/button/stroked/stroked.component.ts b/libs/design/button/src/button/stroked/stroked.component.ts
index ef39a43727..d3762b19ed 100644
--- a/libs/design/button/src/button/stroked/stroked.component.ts
+++ b/libs/design/button/src/button/stroked/stroked.component.ts
@@ -14,7 +14,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffStrokedButtonComponent is a rectangular outlined button with no background color.
  *
- * ## Usage
+ * @example Stroked button
  * ```html
  * <button daff-stroked-button>
  *  <div daffPrefix></div>
diff --git a/libs/design/button/src/button/underline/underline.component.ts b/libs/design/button/src/button/underline/underline.component.ts
index 32f27a81c4..bb96195911 100644
--- a/libs/design/button/src/button/underline/underline.component.ts
+++ b/libs/design/button/src/button/underline/underline.component.ts
@@ -14,7 +14,7 @@ import { DaffButtonBaseDirective } from '../button-base.directive';
 /**
  * DaffUnderlineButtonComponent is a borderless button with a custom underline style.
  *
- * ## Usage
+ * @example Underline button
  * ```html
  * <button daff-underline-button>
  *  <div daffPrefix></div>
diff --git a/libs/design/sidebar/src/sidebar-viewport/sidebar-viewport.component.ts b/libs/design/sidebar/src/sidebar-viewport/sidebar-viewport.component.ts
index 78d503b0c3..9552204928 100644
--- a/libs/design/sidebar/src/sidebar-viewport/sidebar-viewport.component.ts
+++ b/libs/design/sidebar/src/sidebar-viewport/sidebar-viewport.component.ts
@@ -46,23 +46,25 @@ import { DaffSidebarComponent } from '../sidebar/sidebar.component';
 import { DaffSidebarViewportBackdropComponent } from '../sidebar-viewport-backdrop/sidebar-viewport-backdrop.component';
 
 /**
- * The DaffSidebarViewport is the "holder" of sidebars throughout an entire application.
- * It's generally only used once, like
+ * The DaffSidebarViewportComponent is the "holder" of sidebars throughout an entire application.
  *
- * ```html
- * <daff-sidebar-viewport>
- *    <daff-sidebar></daff-sidebar>
- *    <p>Some Content</p>
- * </daff-sidebar-viewport>
- * ```
- *
- * Importantly, its possible for there to be multiple sidebars of many modes
- * at the same time. @see {@link DaffSidebarMode }
+ * `<daff-sidebar-viewport>` should only ever be used once in an application,
+ * but it's possible for there to be multiple sidebars of many modes
+ * at the same time. See {@link DaffSidebarMode}.
  *
  * Since this is a functional component, it's possible to have multiple "open" sidebars
  * at the same time. As a result, this component attempts to gracefully handle these situations.
  * However, importantly, there can only be one sidebar of each mode, on each side, at any given time.
+ *
  * If this is violated, this component will throw an exception.
+ *
+ * @example Using the sidebar viewport
+ * ```html
+ * <daff-sidebar-viewport>
+ *    <daff-sidebar></daff-sidebar>
+ *    <p>Site content</p>
+ * </daff-sidebar-viewport>
+ * ```
  */
 @Component({
   selector: 'daff-sidebar-viewport',
diff --git a/libs/design/src/core/article-encapsulated/article-encapsulated.directive.ts b/libs/design/src/core/article-encapsulated/article-encapsulated.directive.ts
index 07d60be826..e8877f1086 100644
--- a/libs/design/src/core/article-encapsulated/article-encapsulated.directive.ts
+++ b/libs/design/src/core/article-encapsulated/article-encapsulated.directive.ts
@@ -7,15 +7,13 @@ import {
  * `DaffArticleEncapsulatedDirective` is used to encapsulate custom components within an article,
  * preventing {@link DaffArticleComponent } styles from bleeding into the component.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffArticleEncapsulated></my-custom-component>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -25,8 +23,9 @@ import {
  *  hostDirectives: [{ directive: DaffArticleEncapsulatedDirective }],
  * })
  * export class CustomComponent { }
+ * ```
  *
- * This directive will apply the `daff-ae` class to your component, ensuring that it is encapsulated from the article's styles.
+ * This directive will apply the `daff-ae` class to the component, ensuring that it is encapsulated from the article's styles.
  */
 @Directive({
   selector: '[daffArticleEncapsulated]',
diff --git a/libs/design/src/core/colorable/colorable.directive.ts b/libs/design/src/core/colorable/colorable.directive.ts
index dfa7d96432..372d2f9679 100644
--- a/libs/design/src/core/colorable/colorable.directive.ts
+++ b/libs/design/src/core/colorable/colorable.directive.ts
@@ -26,15 +26,36 @@ const validateColor = (color: string) => {
  * styles by setting CSS classes based on the specified color. This directive is useful
  * for applying different color palettes to a component in an Angular application.
  *
- * ## Usage
+ * Supported colors: `primary | secondary | tertiary | black | white | theme | theme-contrast`
  *
- * ### Implementing it as an attribute directive
+ * | Color | Class |
+ * | -------- | ----- |
+ * | `primary` | `.daff-primary`|
+ * | `secondary` | `.daff-secondary`|
+ * | `tertiary` | `.daff-tertiary`|
+ * | `black` | `.daff-black`|
+ * | `white` | `.daff-white`|
+ * | `theme` | `daff-theme`|
+ * | `theme-contrast` | `.daff-theme-contrast`|
+ *
+ * @example Implementing it as an attribute directive
  *
  * ```html
- * <div daffColorable [color]="componentColor">Colored content</div>
+ * <div daffColorable [color]="primary">Colored content</div>
+ * ```
+ *
+ *  ```scss
+ * .div {
+ *  &.daff-primary {
+ *    color: daff-color($primary);
+ *  }
+ * }
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * In this example, the `daff-primary` class is applied to the `div` element, allowing you to
+ * use the color class to style the `div`.
+ *
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -48,30 +69,19 @@ const validateColor = (color: string) => {
  *    },
  *  ],
  * })
- * export class CustomComponent { }
+ * export class CustomComponent {
+ *  @HostBinding('class.custom-component') class = true;
+ * }
  * ```
  *
  * ```scss
  * .custom-component {
- *
  *  &.daff-primary {
  *    background: daff-color($primary, 10);
  *    color: daff-color($primary, 90);
  *  }
  * }
  * ```
- *
- * ## Styles
- *
- * The directive applies the following CSS classes based on the color:
- *
- * - `daff-primary`: Applied when the color is `primary`.
- * - `daff-secondary`: Applied when the color is `secondary`.
- * - `daff-tertiary`: Applied when the color is `tertiary`.
- * - `daff-black`: Applied when the color is `black`.
- * - `daff-white`: Applied when the color is `white`.
- * - `daff-theme`: Applied when the color is `theme`.
- * - `daff-theme-contrast`: Applied when the color is `theme-contrast`.
  */
 @Directive({
   selector: '[daffColorable]',
diff --git a/libs/design/src/core/compactable/compactable.directive.ts b/libs/design/src/core/compactable/compactable.directive.ts
index 8110eca33c..911d9c0b69 100644
--- a/libs/design/src/core/compactable/compactable.directive.ts
+++ b/libs/design/src/core/compactable/compactable.directive.ts
@@ -9,9 +9,7 @@ import {
  * style by toggling a CSS class. This is useful for creating components that can
  * switch between regular and compact styles based on the `compact` property.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffCompactable [compact]="isCompact">Content goes here</div>
@@ -20,7 +18,7 @@ import {
  * In this example, the `daff-compact` class is applied to the `div` element when
  * `isCompact` is `true`, making the `div` display its compact state.
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -37,8 +35,11 @@ import {
  * export class CustomComponent { }
  * ```
  *
+ * The directive applies the `daff-compact` class to the component and
+ * should be defined in your styles to display the compact state as desired.
+ *
  * ```scss
- * .custom-component {
+ * :host {
  *  padding: 8px 16px;
  *
  *  &.daff-compact {
@@ -46,11 +47,6 @@ import {
  *  }
  * }
  * ```
- *
- * ## Styles
- *
- * The `daff-compact` class should be defined in your styles to display the compact
- * state as desired.
  */
 @Directive({
   selector: '[daffCompactable]',
diff --git a/libs/design/src/core/focus/stack.service.ts b/libs/design/src/core/focus/stack.service.ts
index 376c6474c3..2dd8ae0f29 100644
--- a/libs/design/src/core/focus/stack.service.ts
+++ b/libs/design/src/core/focus/stack.service.ts
@@ -25,6 +25,7 @@ export class DaffFocusStackService {
    * Generally, you will probably want to call this before you transition focus
    * onto a new element.
    *
+   * @example Using the push function
    * ```ts
    * this._focusStack.push(this._doc.activeElement);
    * ```
@@ -37,8 +38,9 @@ export class DaffFocusStackService {
   /**
    * Focuses on the HTML element at the top of a stack.
    *
+   * @example Using the focus function
    * ```ts
-   * this._focusStack.push(this._doc.activeElement);
+   * this._focusStack.focus(this._doc.activeElement);
    * ```
    */
   focus() {
diff --git a/libs/design/src/core/manage-container-layout/manage-container-layout.directive.ts b/libs/design/src/core/manage-container-layout/manage-container-layout.directive.ts
index 2f38fb9736..2faaf0ff20 100644
--- a/libs/design/src/core/manage-container-layout/manage-container-layout.directive.ts
+++ b/libs/design/src/core/manage-container-layout/manage-container-layout.directive.ts
@@ -26,9 +26,7 @@ import {
  * while the latter (without `DaffManageContainerLayoutDirective`) may unexpectedly
  * interfere in the layout features of its parent element (i.e. display: grid, display: flex).
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <my-custom-component daffManageContainerLayout>
@@ -43,7 +41,7 @@ import {
  * }
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
diff --git a/libs/design/src/core/openable/openable.directive.ts b/libs/design/src/core/openable/openable.directive.ts
index 65b7a6c5cf..a3604f63ff 100644
--- a/libs/design/src/core/openable/openable.directive.ts
+++ b/libs/design/src/core/openable/openable.directive.ts
@@ -16,7 +16,7 @@ import { DaffOpenableStateError } from './utils/state-error';
  * A directive that opens or closes a component. It should only be used as an [Angular Host Directive](https://angular.dev/guide/directives/directive-composition-api).
  * This directive is stateless by default, but it supports both a state and stateless implementation. Only one version should be used within a component.
  *
- * ## Example
+ * @example Using the DaffOpenableDirective
  * ```ts
  * import {
  *  Component,
@@ -74,6 +74,7 @@ export class DaffOpenableDirective implements DaffOpenable, OnChanges {
 
   /** Whether or not a component should handle state
    *
+   * @example Setting the `stateless` property on a component
    * ```ts
    * constructor(private openDirective: DaffOpenableDirective) {
    *  this.openDirective.stateless = false;
diff --git a/libs/design/src/core/sizable/sizable.directive.ts b/libs/design/src/core/sizable/sizable.directive.ts
index 82e10bcf94..3a64da2775 100644
--- a/libs/design/src/core/sizable/sizable.directive.ts
+++ b/libs/design/src/core/sizable/sizable.directive.ts
@@ -17,9 +17,7 @@ import {
  * `DaffSizableDirective` allows for dynamic sizing of a component by setting
  * CSS classes based on the specified size.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffSizable [size]="small">Sized content</div>
@@ -27,7 +25,7 @@ import {
  * In this example, the `daff-small` class is applied to the `div` element, allowing you to
  * use the class to style the `div`.
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -45,7 +43,7 @@ import {
  * ```
  *
  * ```scss
- * .custom-component {
+ * :host {
  *  &.daff-sm {
  *    width: 24px;
  *  }
@@ -56,9 +54,7 @@ import {
  * }
  * ```
  *
- * ## Styles
- *
- * The directive applies the following CSS classes based on the size:
+ * The directive applies the following CSS classes to the component based on the size:
  *
  * - `daff-xs`: Applied when the size is `xs`.
  * - `daff-sm`: Applied when the size is `sm`.
diff --git a/libs/design/src/core/skeletonable/skeletonable.directive.ts b/libs/design/src/core/skeletonable/skeletonable.directive.ts
index ae63e36bfd..07b55985a6 100644
--- a/libs/design/src/core/skeletonable/skeletonable.directive.ts
+++ b/libs/design/src/core/skeletonable/skeletonable.directive.ts
@@ -12,15 +12,13 @@ import {
  * input property. When `skeleton` is `true`, the `daff-skeleton` CSS class
  * is applied, which should style the component to look like a loading placeholder.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffSkeletonable [skeleton]="isLoading">Content</div>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -38,14 +36,14 @@ import {
  * ```
  *
  * ```scss
- * .daff-skeleton {
- *  @include state.skeleton-screen(48px, 24px);
+ * :host {
+ *  .daff-skeleton {
+ *    @include state.skeleton-screen(48px, 24px);
+ *  }
  * }
  * ```
  *
- * ## Styles
- *
- * The `daff-skeleton` class should be defined in your styles to display the loading
+ * The directive applies the `daff-skeleton` class to the component should be defined in your styles to display the loading
  * state as desired. It can be used in conjuction with the `skeleton-screen` mixin, which provides predefined loading styles.
  */
 @Directive({
diff --git a/libs/design/src/core/statusable/statusable.directive.ts b/libs/design/src/core/statusable/statusable.directive.ts
index 33d63341ec..838bdf1a8f 100644
--- a/libs/design/src/core/statusable/statusable.directive.ts
+++ b/libs/design/src/core/statusable/statusable.directive.ts
@@ -15,15 +15,13 @@ import {
  * styles by setting CSS classes based on the specified status. This directive is useful
  * for indicating different statuses such as info, warning, critical, or success states.
  *
- * ## Usage
- *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffStatusable [status]="componentStatus">Status content</div>
  * ```
  *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -40,17 +38,15 @@ import {
  * export class CustomComponent { }
  *
  * ```scss
- * .custom-component {
- *
+ * :host {
  *  &.daff-critical {
  *    background: daff-color($red, 10);
  *    color: daff-color($red, 90);
  *  }
  * }
  * ```
- * ## Styles
  *
- * The directive applies the following CSS classes based on the status:
+ * The directive applies the following CSS classes to the component based on the status:
  *
  * - `daff-info`: Applied when the status is `info`.
  * - `daff-warn`: Applied when the status is `warn`.
diff --git a/libs/design/src/core/text-alignable/text-alignable.directive.ts b/libs/design/src/core/text-alignable/text-alignable.directive.ts
index 18a784897c..e81d934b4f 100644
--- a/libs/design/src/core/text-alignable/text-alignable.directive.ts
+++ b/libs/design/src/core/text-alignable/text-alignable.directive.ts
@@ -17,19 +17,23 @@ import {
  * setting CSS classes based on the specified text alignment. This directive is
  * useful when text alignment needs to be managed dynamically in an Angular component.
  *
- * ## Usage
+ * ## Why not just use CSS?
+ *
+ * While the native CSS `text-align` property can be used for static text alignment,
+ * the `DaffTextAlignableDirective` provides a structured and consistent way to handle
+ * dynamic text alignment within Angular components in more complex use cases where the
+ * application of `text-align: center;` would cause unexpected side effects.
  *
- * ### Implementing it as an attribute directive
+ * @example Implementing it as an attribute directive
  *
  * ```html
  * <div daffTextAlignable textAlignment="center">Aligned text</div>
+ * ```
  *
  * In this example, the `daff-center` class is added to the `div` element, allowing
  * you to style the `div` as you wish using the class.
  *
- * ```
- *
- * ### Implementing it as an Angular host directive
+ * @example Implementing it as an Angular host directive
  *
  * ```ts
  * @Component({
@@ -53,13 +57,6 @@ import {
  *  }
  * }
  * ```
- *
- * ## Why not just use CSS?
- *
- * While the native CSS `text-align` property can be used for static text alignment,
- * the `DaffTextAlignableDirective` provides a structured and consistent way to handle
- * dynamic text alignment within Angular components in more complex use-cases where the
- * application of `text-align:center` would cause unexpected side effects.
  */
 @Directive({
   selector: '[daffTextAlignable]',
diff --git a/libs/design/switch/src/switch/switch.component.ts b/libs/design/switch/src/switch/switch.component.ts
index cb2bc20b1a..dada9c18e6 100644
--- a/libs/design/switch/src/switch/switch.component.ts
+++ b/libs/design/switch/src/switch/switch.component.ts
@@ -22,11 +22,14 @@ let switchUniqueId = 0;
 /**
  * The switch component provides a way to toggle between two settings.
  *
- * ## Usage
- * <daff-switch [checked]="checked" loading="loading" [error]="true" [labelPosition]="daff-left">
+ * @example
+ *
+ * ```html
+ * <daff-switch [checked]="checked" loading="loading" [error]="true" [labelPosition]="top">
  *    Label
  *    <daff-error-message>Error message</daff-error-message>
  * </daff-switch>
+ * ```
  */
 @Component({
   selector: 'daff-switch',
diff --git a/libs/design/tabs/src/tabs/tab-label/tab-label.component.ts b/libs/design/tabs/src/tabs/tab-label/tab-label.component.ts
index 6dab97a4f6..336356e2f6 100644
--- a/libs/design/tabs/src/tabs/tab-label/tab-label.component.ts
+++ b/libs/design/tabs/src/tabs/tab-label/tab-label.component.ts
@@ -16,6 +16,7 @@ import {
 /**
  * DaffTabLabelComponent is used to display the label of a tab panel. Labels may optionally contain a `daffPrefix` or `daffSuffix` to add icons or badges.
  *
+ * @example Basic structure of tab label
  * ```html
  * <daff-tab-label>
  *  <div daffPrefix></div>
diff --git a/libs/design/tabs/src/tabs/tab-panel/tab-panel.component.ts b/libs/design/tabs/src/tabs/tab-panel/tab-panel.component.ts
index dba50cbe13..cba1665a0b 100644
--- a/libs/design/tabs/src/tabs/tab-panel/tab-panel.component.ts
+++ b/libs/design/tabs/src/tabs/tab-panel/tab-panel.component.ts
@@ -9,6 +9,7 @@ import { DaffTabComponent } from '../tab/tab.component';
 /**
  * DaffTabPanelComponent is used to display the content panel of a tab.
  *
+ * @example Basic structure of tab panel
  * ```html
  * <daff-tab-panel>
  *  <!-- Tab panel content goes here -->
diff --git a/libs/design/tabs/src/tabs/tab/tab.component.ts b/libs/design/tabs/src/tabs/tab/tab.component.ts
index 992df5053c..1a8e5b9a1f 100644
--- a/libs/design/tabs/src/tabs/tab/tab.component.ts
+++ b/libs/design/tabs/src/tabs/tab/tab.component.ts
@@ -11,10 +11,9 @@ let tabId = 1;
 /**
  * `DaffTabComponet` is an element in the tab list that is used as a content container to group the label of a tab panel and the tab panel together.
  *
- * ## Template Structure
  * A `<daff-tab>` should include the {@link DaffTabLabelComponent} and {@link DaffTabPanelComponent} components in order to properly structure the UI.
  *
- * ## Usage
+ * @example Basic structure of tab
  * ```html
  * <daff-tab>
  * 	<daff-tab-label>
@@ -44,6 +43,7 @@ export class DaffTabComponent {
   /**
    * Whether the tab is disabled.
    *
+   * @example Using the `disabled` property
    * ```html
    * <daff-tab [disabled]="true">
    * </daff-tab>
@@ -66,6 +66,7 @@ export class DaffTabComponent {
    *
    * The `id` is automatically generated by linking the prefix 'daff-tab-' with an incrementing `tabId`. This value can be customized by passing a different `id` value via the component's `id` input.
    *
+   * @example Using the `id` property
    * ```html
    * <daff-tab [id]="'custom-id'"></daff-tab>
    * ```
diff --git a/libs/design/tabs/src/tabs/tabs.component.ts b/libs/design/tabs/src/tabs/tabs.component.ts
index dd1180e000..1d489e85bf 100644
--- a/libs/design/tabs/src/tabs/tabs.component.ts
+++ b/libs/design/tabs/src/tabs/tabs.component.ts
@@ -21,7 +21,7 @@ import { DaffTabLabelComponent } from './tab-label/tab-label.component';
 /**
  * Tabs provide a way to navigate between panels that display related content.
  *
- * ## Usage
+ * @example Basic use of the tabs component
  * ```html
  * <daff-tabs aria-label="List of tabs">
  * 	<daff-tab>
diff --git a/libs/design/tree/src/tree-item/tree-item.directive.ts b/libs/design/tree/src/tree-item/tree-item.directive.ts
index 8c0fc59ada..27d82a4419 100644
--- a/libs/design/tree/src/tree-item/tree-item.directive.ts
+++ b/libs/design/tree/src/tree-item/tree-item.directive.ts
@@ -11,10 +11,11 @@ import { DaffTreeNotifierService } from '../tree/tree-notifier.service';
 import { DaffTreeFlatNode } from '../utils/flatten-tree';
 
 /**
- * The `DaffTreeItemDirective` allows you to demarcate the elements which are
- * tree-children that interact with the parent tree.
+ * The `DaffTreeItemDirective` marks elements as tree child nodes that interact with the parent tree structure.
  *
- * They can be used like:
+ * @example Using a `[daffTreeItem]`
+ *
+ * `[tree]` is a {@link DaffTreeData} and `[daff-tree]` is a {@link DaffTreeComponent}.
  *
  * ```html
  * <ul daff-tree [tree]="tree">
@@ -28,8 +29,6 @@ import { DaffTreeFlatNode } from '../utils/flatten-tree';
  * </ul>
  * ```
  *
- * where `tree` is a {@link DaffTreeData} and `daff-tree` is a {@link DaffTreeComponent}.
- *
  */
 @Directive({
   selector: '[daffTreeItem]',
@@ -38,7 +37,7 @@ import { DaffTreeFlatNode } from '../utils/flatten-tree';
 export class DaffTreeItemDirective {
 
   /**
-   * The css class of the daff-tree.
+   * The css class of the tree item.
    *
    * @docs-private
    */
diff --git a/libs/design/tree/src/tree/tree.component.ts b/libs/design/tree/src/tree/tree.component.ts
index 2a079ccff6..b23c9683cd 100644
--- a/libs/design/tree/src/tree/tree.component.ts
+++ b/libs/design/tree/src/tree/tree.component.ts
@@ -30,8 +30,7 @@ import { hydrateTree } from '../utils/hydrate-tree';
 /**
  * The `DaffTreeComponent` allows you to render tree structures as interactable ui.
  *
- * They can be used like:
- *
+ * @example Basic use of the tree component
  * ```html
  * <ul daff-tree [tree]="tree">
  *   <ng-template #daffTreeItemWithChildrenTpl let-node>