generate-docs

name	generate-docs
description	How to (re)generate the API reference doc/api.md for node-telegram-bot-api. Use whenever a public Api method, class, function, or type is added/removed/changed, or when a PR check reports doc/api.md is out of date. Covers the two-stage pipeline (TypeDoc -> doc/api.json -> doc/api.md via scripts/generate-docs.ts), what it does and does not capture, and how to verify the result is committed.

Generating doc/api.md

doc/api.md is the human-readable API reference. It is generated, not hand-edited, and checked into git - so it must be regenerated and committed whenever the public surface changes. The intermediate doc/api.json is gitignored.

Command

npm run generate:docs        # == bun scripts/generate-docs.ts

This runs the two stages (see below) and prints a summary of how many classes, functions, interfaces, enums, type aliases, and variables it wrote. It needs no token and no network - TypeDoc reads the local TypeScript source.

The two-stage pipeline

scripts/generate-docs.ts deliberately separates parsing from presentation:

1. TypeDoc -> doc/api.json. The script boots TypeDoc on the package entry points (src/core/index.ts, src/node/index.ts) and calls app.generateJson(project, ...). TypeDoc owns the type graph - generics, unions, literal types, intersections, and cross-references - and serializes the full project reflection to JSON. Private, protected, and @internal members are excluded (excludePrivate / excludeProtected / excludeInternal).
2. JSON -> doc/api.md. A small hand-written renderer walks the JSON and emits Markdown: a methods table per class (with each method's params, return type, and a per-method description), param/return tables for functions, property tables for interfaces, and a section per type alias / variable / enum. Type references to other documented declarations become in-page links. It imports TypeDoc's public ReflectionKind enum so the kind numbers track the installed TypeDoc version.

Why the split: TypeDoc is the robust parser; the script is the only place that decides what the docs look like. The JSON stays on disk as an inspectable intermediate.

When to run

Regenerate after any change to the public surface:

• adding, removing, or renaming a class, function, interface, enum, variable, or exported type alias;
• changing a method's parameters, return type, or its Api-method {@link} comment;
• regenerating types with npm run generate:types (new methods/types appear automatically).

You do not need to run it for changes to method bodies that don't change a signature, or for private/internal code.

The per-method description column

Each class method's "Description" column renders the full comment summary: for generated Api methods that is the {@link} to the official Bot API page (emitted as a TSDoc comment by the type generator, scripts/api-parser.ts); for hand-written library methods (Bot.command, Context.reply, builders) it is the prose description. To change the Api links, change the type generator - do not hand-edit src/core/api.ts.

Verify before committing

The doc must match the source. Confirm regenerating produces no diff:

npm run generate:docs
git diff --exit-code doc/api.md   # exit 0 = up to date

If git diff shows changes, commit the regenerated doc/api.md alongside your code change. doc/api.json is gitignored - never commit it.

This is separate from npm run generate:types (which regenerates src/types/schemas.ts and src/core/api.ts from the live Telegram docs). If you regenerate types and that adds/changes the public surface, regenerate docs too.

Tweak the presentation

Output layout (tables vs. fenced blocks, what gets a heading, how a type renders) lives entirely in scripts/generate-docs.ts. In particular renderType handles each TypeDoc type variant; add a case there if a new type shape renders poorly, and slug() must keep matching GitHub's anchor algorithm (it preserves underscores) so in-page links resolve.