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

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 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—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 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:

• 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 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 file bridges the parsing infrastructure to the public API. It imports help from 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

// 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:

/**
 * 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	Parses bundled JavaScript with Acorn, extracts JSDoc, builds help strings
src/helpers.ts	Imports help and exposes it in the agent-facing helper context
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 source
• Bundle generation preserves comments; no separate documentation build step exists
• src/help-runtime.ts implements AST parsing and JSDoc extraction
• src/format.ts transforms parsed comments into readable help output
• 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. 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. 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}