From abc3ccbc116a973d2415c0cc7beb43ad5d048b7b Mon Sep 17 00:00:00 2001
From: Logan Markewich <logan.markewich@live.com>
Date: Tue, 9 Sep 2025 16:51:35 -0600
Subject: [PATCH] add more typedoc references

---
 packages/core/src/middleware/state.ts         | 46 +++++++++++++++++
 packages/core/src/middleware/trace-events.ts  | 44 ++++++++++++++++
 .../trace-events/create-handler-decorator.ts  | 50 +++++++++++++++++++
 packages/core/typedoc.json                    |  7 ++-
 packages/viz/src/drawing.ts                   | 45 +++++++++++++++++
 5 files changed, 191 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/middleware/state.ts b/packages/core/src/middleware/state.ts
index 315c971..8f01132 100644
--- a/packages/core/src/middleware/state.ts
+++ b/packages/core/src/middleware/state.ts
@@ -90,6 +90,52 @@ type CreateState<State, Input, Context extends WorkflowContext> = {
 
 type InitFunc<Input, State> = (input: Input) => State;
 
+/**
+ * Creates a stateful middleware that adds state management capabilities to workflows.
+ *
+ * The stateful middleware allows workflows to maintain persistent state across handler executions,
+ * with support for snapshots and resuming workflow execution from saved states.
+ *
+ * @typeParam State - The type of state object to maintain
+ * @typeParam Input - The type of input used to initialize the state (defaults to void)
+ * @typeParam Context - The workflow context type (defaults to WorkflowContext)
+ *
+ * @param init - Optional initialization function that creates the initial state from input
+ * @returns A middleware object with state management capabilities
+ *
+ * @example
+ * ```typescript
+ * import { createWorkflow, workflowEvent } from "@llamaindex/workflow-core";
+ * import { createStatefulMiddleware } from "@llamaindex/workflow-core/middleware/state";
+ *
+ * // Define your state type
+ * type MyState = {
+ *   counter: number;
+ *   messages: string[];
+ * };
+ *
+ * // Create the stateful middleware
+ * const stateful = createStatefulMiddleware<MyState>();
+ * const workflow = stateful.withState(createWorkflow());
+ *
+ * // Use state in handlers
+ * workflow.handle([inputEvent], async (context, event) => {
+ *   const { state, sendEvent } = context;
+ *   state.counter += 1;
+ *   state.messages.push(`Processed: ${event.data}`);
+ *   sendEvent(outputEvent.with({ count: state.counter }));
+ * });
+ *
+ * // Initialize with state
+ * const { sendEvent, snapshot } = workflow.createContext({
+ *   counter: 0,
+ *   messages: []
+ * });
+ * ```
+ *
+ * @category Middleware
+ * @public
+ */
 export function createStatefulMiddleware<
   State,
   Input = void,
diff --git a/packages/core/src/middleware/trace-events.ts b/packages/core/src/middleware/trace-events.ts
index d13ee0d..07eb139 100644
--- a/packages/core/src/middleware/trace-events.ts
+++ b/packages/core/src/middleware/trace-events.ts
@@ -81,6 +81,50 @@ export type WithTraceEventsOptions = {
   plugins?: TracePlugin[];
 };
 
+/**
+ * Adds tracing capabilities to a workflow by wrapping handlers with trace plugins.
+ *
+ * This middleware enables comprehensive tracing and monitoring of workflow execution,
+ * allowing you to attach plugins that can observe, measure, and instrument handler execution.
+ *
+ * @typeParam WorkflowLike - The workflow type to enhance with tracing
+ *
+ * @param workflow - The workflow instance to add tracing to
+ * @param options - Configuration object containing trace plugins
+ * @returns The workflow enhanced with tracing capabilities
+ *
+ * @example
+ * ```typescript
+ * import { createWorkflow, workflowEvent } from "@llamaindex/workflow-core";
+ * import { withTraceEvents } from "@llamaindex/workflow-core/middleware/trace-events";
+ *
+ * // Define events
+ * const startEvent = workflowEvent();
+ * const processEvent = workflowEvent<string>();
+ *
+ * // Create a simple timing plugin
+ * const timingPlugin = (handler) => async (...args) => {
+ *   const start = Date.now();
+ *   try {
+ *     return await handler(...args);
+ *   } finally {
+ *     console.log(`Handler took ${Date.now() - start}ms`);
+ *   }
+ * };
+ *
+ * // Apply tracing to workflow
+ * const workflow = withTraceEvents(createWorkflow(), {
+ *   plugins: [timingPlugin]
+ * });
+ *
+ * workflow.handle([startEvent], (context) => {
+ *   context.sendEvent(processEvent.with("data"));
+ * });
+ * ```
+ *
+ * @category Middleware
+ * @public
+ */
 export function withTraceEvents<
   WorkflowLike extends {
     handle<
diff --git a/packages/core/src/middleware/trace-events/create-handler-decorator.ts b/packages/core/src/middleware/trace-events/create-handler-decorator.ts
index 282c9db..040d737 100644
--- a/packages/core/src/middleware/trace-events/create-handler-decorator.ts
+++ b/packages/core/src/middleware/trace-events/create-handler-decorator.ts
@@ -26,6 +26,56 @@ export const decoratorRegistry = new Map<
   }
 >();
 
+/**
+ * Creates a handler decorator that can instrument workflow handlers with custom behavior.
+ *
+ * Handler decorators allow you to wrap workflow handlers with additional functionality
+ * such as logging, timing, error handling, or state management. They provide hooks
+ * that run before and after handler execution.
+ *
+ * @typeParam Metadata - The type of metadata to track for each handler
+ *
+ * @param config - Configuration object for the decorator
+ * @param config.debugLabel - Optional debug label for identifying the decorator
+ * @param config.getInitialValue - Function that returns initial metadata value
+ * @param config.onBeforeHandler - Hook that runs before handler execution
+ * @param config.onAfterHandler - Hook that runs after handler execution
+ * @returns A decorator function that can be used as a trace plugin
+ *
+ * @example
+ * ```typescript
+ * import { createWorkflow, workflowEvent } from "@llamaindex/workflow-core";
+ * import {
+ *   withTraceEvents,
+ *   createHandlerDecorator
+ * } from "@llamaindex/workflow-core/middleware/trace-events";
+ *
+ * // Create a timing decorator
+ * type TimingMetadata = { startTime: number | null };
+ * const timingDecorator = createHandlerDecorator<TimingMetadata>({
+ *   debugLabel: "timing",
+ *   getInitialValue: () => ({ startTime: null }),
+ *   onBeforeHandler: (handler, context, metadata) => async (...args) => {
+ *     metadata.startTime = Date.now();
+ *     try {
+ *       return await handler(...args);
+ *     } finally {
+ *       const duration = Date.now() - (metadata.startTime ?? 0);
+ *       console.log(`Handler executed in ${duration}ms`);
+ *     }
+ *   },
+ *   onAfterHandler: () => ({ startTime: null })
+ * });
+ *
+ * // Use the decorator
+ * const workflow = withTraceEvents(createWorkflow(), {
+ *   plugins: [timingDecorator]
+ * });
+ * ```
+ *
+ * @category Middleware
+ * @public
+ */
 export function createHandlerDecorator<Metadata>(config: {
   debugLabel?: string;
   getInitialValue: () => Metadata;
diff --git a/packages/core/typedoc.json b/packages/core/typedoc.json
index ff1e76c..f3f776f 100644
--- a/packages/core/typedoc.json
+++ b/packages/core/typedoc.json
@@ -1,6 +1,11 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./src/core/index.ts"],
+  "entryPoints": [
+    "./src/core/index.ts",
+    "./src/middleware/state.ts",
+    "./src/middleware/trace-events.ts",
+    "./src/middleware/trace-events/create-handler-decorator.ts"
+  ],
   "out": "../../docs/workflows/api-reference",
   "plugin": ["typedoc-plugin-markdown"],
   "outputFileStrategy": "members",
diff --git a/packages/viz/src/drawing.ts b/packages/viz/src/drawing.ts
index f52608a..ffc55bd 100644
--- a/packages/viz/src/drawing.ts
+++ b/packages/viz/src/drawing.ts
@@ -13,6 +13,51 @@ export type WithDrawingWorkflow = {
   draw(container: HTMLElement, options?: DrawingOptions): void;
 };
 
+/**
+ * Adds visualization capabilities to a workflow, enabling it to be rendered as an interactive graph.
+ *
+ * This function enhances a workflow with drawing functionality, allowing you to visualize
+ * the flow of events and handlers as an interactive graph in the browser using Sigma.js.
+ *
+ * @typeParam WorkflowLike - The workflow type to enhance with drawing capabilities
+ *
+ * @param workflow - The workflow instance to add visualization to
+ * @returns The workflow enhanced with a `draw` method for rendering graphs
+ *
+ * @example
+ * ```typescript
+ * import { createWorkflow, workflowEvent } from "@llamaindex/workflow-core";
+ * import { withDrawing } from "@llamaindex/workflow-viz";
+ *
+ * // Define events with debug labels for better visualization
+ * const startEvent = workflowEvent<string>({ debugLabel: "start" });
+ * const processEvent = workflowEvent<string>({ debugLabel: "process" });
+ * const endEvent = workflowEvent<string>({ debugLabel: "end" });
+ *
+ * // Create workflow with drawing capabilities
+ * const workflow = withDrawing(createWorkflow());
+ *
+ * // Add handlers
+ * workflow.handle([startEvent], (context, event) => {
+ *   return processEvent.with(`Processing: ${event.data}`);
+ * });
+ *
+ * workflow.handle([processEvent], (context, event) => {
+ *   return endEvent.with(`Completed: ${event.data}`);
+ * });
+ *
+ * // Render the workflow graph
+ * const container = document.getElementById("workflow-container");
+ * workflow.draw(container, {
+ *   layout: "force",
+ *   defaultEdgeColor: "#999",
+ *   defaultNodeColor: "#333"
+ * });
+ * ```
+ *
+ * @category Visualization
+ * @public
+ */
 export function withDrawing<WorkflowLike extends Workflow>(
   workflow: WorkflowLike,
 ): WorkflowLike & WithDrawingWorkflow {