From 24d893d401c1c86da445f7e6bd3492ccbec7c978 Mon Sep 17 00:00:00 2001
From: Connor Byrne <c.byrne@comfy.org>
Date: Thu, 21 May 2026 14:01:24 -0700
Subject: [PATCH] docs(ext-api): lift @example onto shell-UI type declarations
 (close W17.N.2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

typedoc renders re-exported type pages from the original-declaration
site (src/types/extensionTypes.ts), not from the @comfyorg/extension-api
barrel re-export. The shell-UI type aliases (ToastMessageOptions,
HotkeyExtension, AboutBadgeExtension, ToolbarButtonExtension) therefore
shipped to the dashboard without any @example blocks even though their
matching defineX entry points carry full examples in registrations.ts /
imperatives.ts.

Lift the canonical @example from each defineX onto the source
declaration so the dashboard type page renders with a working snippet.

Pure JSDoc — zero exported-type diff. Phase A freeze respected.

Wave-18 W18.J. Closes W17.N.2.
---
 src/types/extensionTypes.ts | 40 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/src/types/extensionTypes.ts b/src/types/extensionTypes.ts
index 1c539eeaaa..f4cae594c9 100644
--- a/src/types/extensionTypes.ts
+++ b/src/types/extensionTypes.ts
@@ -49,7 +49,17 @@ export type BottomPanelExtension =
   | CustomBottomPanelExtension
 
 /**
- * Defines message options in Toast component.
+ * Defines message options in Toast component. Passed to {@link toast.show} /
+ * {@link toast.remove} to surface a transient message to the user.
+ *
+ * @publicAPI
+ * @stability experimental
+ * @example
+ * ```ts
+ * import { toast } from '@comfyorg/extension-api'
+ *
+ * toast.show({ severity: 'info', summary: 'Saved', life: 2000 })
+ * ```
  */
 export interface ToastMessageOptions {
   /**
@@ -180,6 +190,13 @@ export type CommandDefinition = ComfyCommand
  *
  * @publicAPI
  * @stability experimental
+ * @example
+ * ```ts
+ * import { defineCommand, defineHotkey } from '@comfyorg/extension-api'
+ *
+ * defineCommand({ id: 'my.cmd', function: () => {} })
+ * defineHotkey({ keys: 'mod+k', commandId: 'my.cmd' })
+ * ```
  */
 export interface HotkeyExtension {
   /**
@@ -206,6 +223,16 @@ export interface HotkeyExtension {
  *
  * @publicAPI
  * @stability experimental
+ * @example
+ * ```ts
+ * import { defineAboutBadge } from '@comfyorg/extension-api'
+ *
+ * defineAboutBadge({
+ *   label: 'GitHub',
+ *   url: 'https://github.com/me/my-ext',
+ *   icon: 'pi-github'
+ * })
+ * ```
  */
 export interface AboutBadgeExtension {
   /** Display label for the badge. */
@@ -246,6 +273,17 @@ export type SettingDefinition<TValue = unknown> = SettingParams<TValue>
  *
  * @publicAPI
  * @stability experimental
+ * @example
+ * ```ts
+ * import { defineToolbarButton } from '@comfyorg/extension-api'
+ *
+ * defineToolbarButton({
+ *   id: 'my.help',
+ *   icon: 'pi-question-circle',
+ *   tooltip: 'Get help',
+ *   onClick: () => openHelp()
+ * })
+ * ```
  */
 export interface ToolbarButtonExtension {
   /** Stable id for the button — used by `dispose()` to unregister. */