docs: generate STDLIB.md / BUILTINS.md from structured doc-comments instead of hand-writing them
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 45/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- c
- Domain
- developer-experience, documentation
Research direction
Examine the existing hand-written docs in docs/STDLIB.md and docs/BUILTINS.md, and the source files in lib/*.eigs and the C registration sites for builtins. Understand the current drift gate in tools/stdlib_index_check.sh and the executed-fence machinery in tests/test_doc_examples.py. The goal is to design a structured doc-comment convention, implement a generator, and integrate it into the build process to auto-generate the documentation tables.
Written by the indexing model from the issue text.
Description
Problem. docs/STDLIB.md (1,851 lines) and docs/BUILTINS.md (986) are hand-written. A drift gate (tools/stdlib_index_check.sh) catches mismatches, but a person still types every entry, and the lib/*.eigs headers are free-form comments (e.g. lib/json.eigs's "How to use:" block), not structured doc-comments.
What mature languages do. The API reference is generated from the source: rustdoc from ///, go doc / pkg.go.dev from comments, Sphinx autodoc, ExDoc from @doc. The reference cannot drift, because it is the code.
Bar.
- A structured doc-comment convention for
lib/*.eigspublic functions (signature, one-line summary, args, return, an example that runs), documented indocs/STDLIB.md's preamble or CONTRIBUTING. - A C-side description for every builtin at its registration site (where
eigenscript --apialready enumerates the surface). - A generator produces the module/function tables of STDLIB.md and BUILTINS.md. Hand-written prose sections may stay, fenced off from the generated regions.
- The drift gate becomes "regenerate and diff": a new function without a doc-comment fails by name, and so does an edited generated region.
- The doc examples extracted from doc-comments run under the existing executed-fence machinery (
tests/test_doc_examples.py).
Ranked #2 of the docs follow-ups (2026-09-22 comparison with other languages).
- Dominant language
- C
- Stars
- 3
- Forks
- 7
- Avg merge
- 3h 58m
- Merged PRs (30d)
- 105
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from InauguralSystems/EigenScript
-
area:lint-tooling bug
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
InauguralSystems/EigenScript#1340 ·
Maintainers usually reply within 1 day
-
area:stdlib found-by:code-review kind:silent-wrong
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
InauguralSystems/EigenScript#1338 ·
Maintainers usually reply within 1 day
-
area:lint-tooling found-by:critic kind:docs-drift
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
InauguralSystems/EigenScript#1335 ·
Maintainers usually reply within 1 day
-
area:ci found-by:critic kind:gate-defect
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
InauguralSystems/EigenScript#1311 ·
Maintainers usually reply within 1 day
-
enrolment: decide test_gc_runner_controls.py (exempt vs enrol) and whether floors need a ratchetOpenarea:gates found-by:critic kind:decision
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
InauguralSystems/EigenScript#1280 · 1 comment ·
Maintainers usually reply within 1 day
All issues in InauguralSystems/EigenScript
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
NabuCasa/silabs-firmware-builder#231 · 1 comment ·
-
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
ClickHouse/pg_clickhouse#383 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day