These days, it's essential to make API documentation easily discoverable by an AI coding agent.
Some suggestions:
-
API surface table in the package README — a single table listing every exported function with its signature and one-line purpose. Parsers and serializers are the natural pair; showing them together eliminates the "is there a serializer?" question entirely:
| Function | Input | Output |
| Gram.parse(text) | string | Effect<Pattern[], GramParseError> |
| Gram.stringify(ps) | ReadonlyArray | Effect<string, GramParseError> |
-
A round-trip example at the top — one code snippet showing parse → modify → stringify is the most common real-world use case and makes both functions discoverable simultaneously.
-
llms.txt or AI.md at the repo root — the emerging convention for AI-readable documentation. A flat file with all public API signatures, no prose, no navigation. AI tools and code agents read it directly. See https://llmstxt.org for the format.
-
JSDoc on exported functions — @param, @returns, and a one-line description on each export. These appear in IDE tooltips and get picked up by code intelligence tools that don't fetch web pages.
This repo is a multi-language repo, so this is even more complicated. Ideally use these suggestions as entry points that point to a hosted API documentation using gh-pages.
These days, it's essential to make API documentation easily discoverable by an AI coding agent.
Some suggestions:
API surface table in the package README — a single table listing every exported function with its signature and one-line purpose. Parsers and serializers are the natural pair; showing them together eliminates the "is there a serializer?" question entirely:
| Function | Input | Output |
| Gram.parse(text) | string | Effect<Pattern[], GramParseError> |
| Gram.stringify(ps) | ReadonlyArray | Effect<string, GramParseError> |
A round-trip example at the top — one code snippet showing parse → modify → stringify is the most common real-world use case and makes both functions discoverable simultaneously.
llms.txt or AI.md at the repo root — the emerging convention for AI-readable documentation. A flat file with all public API signatures, no prose, no navigation. AI tools and code agents read it directly. See https://llmstxt.org for the format.
JSDoc on exported functions — @param, @returns, and a one-line description on each export. These appear in IDE tooltips and get picked up by code intelligence tools that don't fetch web pages.
This repo is a multi-language repo, so this is even more complicated. Ideally use these suggestions as entry points that point to a hosted API documentation using gh-pages.