# How the ego-lite `help()` Function Uses JSDoc Parsing for Runtime Documentation

> Discover how ego-lite's help() function uses JSDoc parsing at runtime via a pre-computed map for instant, efficient documentation access. Learn more!

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

---

**The `help()` function in citrolabs/ego-lite queries a pre-computed documentation map generated at build time from JSDoc comments, enabling instant runtime access without file-system operations or parsing overhead.**

In the citrolabs/ego-lite repository, the `help()` utility provides interactive documentation for helper functions by leveraging a sophisticated build-time pipeline that extracts JSDoc metadata and embeds it directly into the runtime bundle. This approach eliminates the need for the browser or runtime environment to parse source code files, instead relying on a baked-in JSON documentation map that is loaded on demand. Understanding how the `help()` function is implemented using JSDoc parsing at runtime requires examining the three-stage pipeline: extraction, embedding, and lookup.

## Build-Time JSDoc Extraction Pipeline

The documentation generation begins long before the code reaches the browser. The `scripts/extract-help-docs.mjs` script analyzes the bundled JavaScript using the **Acorn** parser to create an AST, then walks the tree to find block comments preceding function declarations.

### Parsing the Source with Acorn

Inside `extract-help-docs.mjs`, the `parse()` function from Acorn processes the bundled JavaScript to produce an AST. The extractor collects all block comments and correlates each comment with the immediately following function declaration. This correlation ensures that documentation attaches to the correct helper regardless of minification or bundling artifacts.

### Structuring Helper Documentation

Once a comment block is identified, the `parseJSDoc()` function transforms the raw JSDoc into a structured object containing `description`, `params`, and `returns` fields. The `extractParams()` helper enriches this data by walking the AST to resolve default values, identify rest parameters (`...args`), and flag optional parameters. Each helper yields a **HelperDoc** object containing:

- The helper name and signature
- Parameter list with types and descriptions
- Return type annotation
- Async flag status

The `extractHelpDocs()` function returns an array of these objects, ready for serialization.

## Embedding Documentation into the Runtime

During the bundling phase, `scripts/build.mjs` executes the extraction and embeds the results into the runtime. The `embedHelpDocs` routine JSON-stringifies the `HelperDoc` array and injects it into [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts), replacing the placeholder string `__EGO_EMBEDDED_HELP_DOCS__`. This compile-time injection means the runtime code carries its own documentation payload, requiring no external file access to serve help content.

## Runtime Lookup and Caching

At runtime, [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) implements the public `help()` API. Rather than parsing comments, it operates on the embedded JSON data through an efficient caching mechanism.

### The getDocsMap() Cache

The `getDocsMap()` function lazily deserializes the injected JSON using `parseEmbeddedDocs()` and stores the result in a `Map<string, HelperDoc>`. This cache persists for the lifetime of the module, ensuring repeated calls to `help()` return instantly without re-parsing the JSON payload.

### Three Query Modes

The `help()` function supports three distinct calling conventions:

- **No arguments** – Returns documentation for all available helpers present in the current helpers object.
- **Single string** – Returns the `HelperDoc` for the specified helper name, or an "Unknown helper" string if not found.
- **Multiple strings** – Returns an array of `HelperDoc` objects, inserting a placeholder object for any unrecognized names.

## Formatting Helper Documentation

For human-readable output, the `formatHelp()` function (located in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts)) consumes a `HelperDoc` object and generates a formatted string. The output includes the description, `@param` lines with types and defaults, the `@returns` annotation, and a reconstructed function signature showing parameter optionality.

```javascript
// Query examples assuming the ego-lite helper context
console.log(help());                         // Array of all helper docs
console.log(help('click'));                  // Doc for the 'click' helper
console.log(help('click', 'type', 'foo'));   // Docs for click, type, and placeholder for foo

// Pretty-print a single helper
const doc = help('click');
console.log(formatHelp(doc));

```

Typical output includes the description, parameter details, and signature:

```

Clicks an element located by a CSS selector.
@param selector string — The CSS selector of the element.
@param button? string — Mouse button to press (default: "left").
@returns void

click(selector, button?) → void

```

## Summary

- **Build-time extraction**: `scripts/extract-help-docs.mjs` uses Acorn to parse JSDoc comments from the bundled source and creates structured `HelperDoc` objects.
- **Compile-time embedding**: `scripts/build.mjs` injects the JSON-serialized documentation into [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) via the `__EGO_EMBEDDED_HELP_DOCS__` placeholder.
- **Runtime caching**: `getDocsMap()` lazily parses the embedded JSON once and caches it in a Map for O(1) lookups.
- **Multiple access patterns**: `help()` supports querying all helpers, single helpers by name, or multiple helpers in one call.
- **Formatting utility**: `formatHelp()` renders `HelperDoc` objects into human-readable strings with signatures and parameter descriptions.

## Frequently Asked Questions

### Does help() parse JSDoc comments at runtime?

No. The `help()` function reads from a pre-computed JSON map that was generated at build time. The actual JSDoc parsing occurs in `scripts/extract-help-docs.mjs` using the Acorn parser, long before the code executes in the browser or runtime environment.

### What tool extracts the JSDoc metadata for embedding?

The extraction is performed by the Node.js script `scripts/extract-help-docs.mjs`. This script uses Acorn to generate an AST from the bundled JavaScript, then walks the tree to match block comments with function declarations and resolve parameter details via `extractParams()`.

### How does the runtime access the embedded documentation?

The bundled JavaScript contains a placeholder string `__EGO_EMBEDDED_HELP_DOCS__` that gets replaced with the stringified JSON documentation array during the build process. At runtime, `getDocsMap()` in [`src/help-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/help-runtime.ts) parses this JSON once and caches the results in a Map keyed by helper name.

### What information is stored in a HelperDoc object?

Each `HelperDoc` contains the helper name, function signature, JSDoc description, an array of parameter objects (with names, types, defaults, and optionality flags), the return type, and a boolean indicating whether the function is async.