# How the Ego-Browser Help System Generates Documentation from JSDoc at Runtime

> Discover how ego-browser generates runtime documentation from JSDoc comments using Acorn parsing. Learn how this eliminates the need for a separate build step in your JavaScript projects.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: internals
- Published: 2026-08-06

---

**The `help()` function in ego-browser parses JSDoc comments directly from the bundled JavaScript source using Acorn, extracting documentation at runtime without requiring a separate build step.**

The `ego-browser` package in the [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) repository implements a self-documenting runtime where agent-facing helpers remain documented through their original source comments. This article explains how the help system transforms embedded JSDoc into interactive documentation that agents can query on demand.

## The Runtime Documentation Pipeline

Documentation generation in ego-browser follows a three-stage pipeline: **bundle preservation**, **AST parsing**, and **formatting**. Each stage ensures that what agents see reflects the actual code being executed.

### Bundle Generation Preserves JSDoc Comments

When you run `npm run build`, the TypeScript compiler produces [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js)—a single JavaScript bundle containing all exported helpers. Unlike typical production builds that strip comments for size, this process **retains JSDoc annotations** attached to exported functions. The preserved comments become the raw material for runtime documentation extraction.

### Runtime Parsing with Acorn

The [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) module implements the core parsing logic. At runtime, it loads the bundle's source code and feeds it to **Acorn**, a lightweight JavaScript parser. The module walks the resulting AST to identify exported functions and extracts the JSDoc comment blocks that precede each export declaration.

Key implementation details from [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts):

- Uses Acorn to parse the bundled JavaScript into an AST
- Traverses the AST to locate `ExportNamedDeclaration` nodes
- Extracts leading comment blocks matching the JSDoc pattern (`/** ... */`)

### Formatting JSDoc for Human Readability

Raw JSDoc AST nodes require transformation before presentation. The `formatHelp` function in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts) handles this conversion, turning parsed tags (`@param`, `@returns`, etc.) into **markdown-style help strings** suitable for terminal or agent consumption.

## How the Help System Integrates with the Agent API

The [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) file bridges the parsing infrastructure to the public API. It imports `help` from [`help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/help-runtime.ts) and re-exports it as part of the helper context that agent scripts can invoke.

This wiring means agents call `help()` as a first-class helper, even though its implementation lives separately from the core browser automation primitives.

### Calling Help from an Agent Script

```javascript
// List all available helpers with their documentation
await help();

// Example output showing JSDoc-derived documentation:
//
// click(loc, opts) – Clicks an element identified by a locator.
//     loc – The locator string (e.g., "css:#submit").
//     opts – Optional click options.

```

## JSDoc Structure in Source Files

The documentation quality depends on consistent JSDoc formatting in the source. Consider this example from the helpers:

```javascript
/**
 * Clicks an element identified by a locator.
 *
 * @param {string} loc - The locator string (e.g., "css:#submit").
 * @param {object} [opts] - Optional click options.
 */
export async function click(loc, opts) {
  // implementation …
}

```

When bundled and loaded, this function's JSDoc block is parsed, its `@param` tags extracted, and the description formatted into the help output shown above. The optional parameter notation `[opts]` is preserved in the signature display.

## Why Runtime Documentation Generation Matters

**No separate documentation build**: Changes to JSDoc comments are immediately reflected in `help()` output after rebuilding the bundle—no static site generation or markdown preprocessing required.

**Guaranteed accuracy**: Since documentation is extracted from the actual executed code, version skew between docs and implementation is impossible.

**Minimal runtime overhead**: Parsing occurs only when `help()` is invoked; normal agent execution incurs no documentation-related cost.

## Key Source Files

| File | Role |
|------|------|
| [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) | Parses bundled JavaScript with Acorn, extracts JSDoc, builds help strings |
| [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) | Imports `help` and exposes it in the agent-facing helper context |
| [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts) | Transforms raw JSDoc AST into formatted markdown-style text |

Per the source code in `citrolabs/ego-lite`, these three modules cooperate to deliver the runtime documentation experience without external dependencies beyond Acorn itself.

## Summary

- The `help()` function parses JSDoc at runtime using Acorn on the bundled [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js) source
- Bundle generation preserves comments; no separate documentation build step exists
- [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) implements AST parsing and JSDoc extraction
- [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts) transforms parsed comments into readable help output
- [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) wires the help system into the public agent API
- Documentation always reflects the currently executing code version

## Frequently Asked Questions

### What parser does ego-browser use for JSDoc extraction?

Ego-browser uses **Acorn**, a small, fast JavaScript parser implemented in [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts). Acorn generates an AST from the bundle source, which the help system traverses to locate and extract JSDoc comment blocks preceding exported functions.

### Does the build process strip JSDoc comments from the bundle?

No. The TypeScript compilation in `npm run build` intentionally **preserves JSDoc comments** in [`dist/out/index.js`](https://github.com/citrolabs/ego-lite/blob/main/dist/out/index.js). This preservation is essential for the runtime help system to function, as it relies on parsing these comments directly from the bundle.

### Can agents access documentation for individual helpers?

The current implementation in [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) generates a complete listing of all exported helpers. While the parsed AST contains sufficient information to support single-function queries, the public `help()` API returns the full documentation set as shown in the usage example.

### What happens if JSDoc syntax is malformed?

The `formatHelp` function in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts) processes whatever comment blocks Acorn identifies as JSDoc. Malformed tags may result in incomplete or unformatted output, but the parsing itself is tolerant—Acorn extracts the comment text regardless of internal tag validity.