docs: generate STDLIB.md / BUILTINS.md from structured doc-comments instead of hand-writing them
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 新手友好度
- 45/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 活跃
- 技术栈
- c
调研方向
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.
由索引模型根据 Issue 内容生成。
描述
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).
- 主要语言
- C
- 星标
- 3
- 派生
- 7
- 平均合并
- 3 小时 58 分钟
- 30 天内合并 PR
- 105
环境准备
在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。
- 提供 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
InauguralSystems/EigenScript 的其他 Issue
-
area:lint-tooling bug
难度 2/5 1-3 小时 新手友好度 88/100
InauguralSystems/EigenScript#1340 ·
维护者通常 1 天内回复
-
area:stdlib found-by:code-review kind:silent-wrong
难度 2/5 1-3 小时 新手友好度 88/100
InauguralSystems/EigenScript#1338 ·
维护者通常 1 天内回复
-
area:lint-tooling found-by:critic kind:docs-drift
难度 2/5 1-3 小时 新手友好度 76/100
InauguralSystems/EigenScript#1335 ·
维护者通常 1 天内回复
-
area:ci found-by:critic kind:gate-defect
难度 2/5 1-3 小时 新手友好度 86/100
InauguralSystems/EigenScript#1311 ·
维护者通常 1 天内回复
-
enrolment: decide test_gc_runner_controls.py (exempt vs enrol) and whether floors need a ratchet未关闭area:gates found-by:critic kind:decision
难度 2/5 1-3 小时 新手友好度 65/100
InauguralSystems/EigenScript#1280 · 1 条评论 ·
维护者通常 1 天内回复
查看 InauguralSystems/EigenScript 的全部 Issue
相似的 Issue
-
难度 1/5 1-3 小时 新手友好度 88/100
ClickHouse/pg_clickhouse#383 · 1 条评论 ·
维护者通常 1 天内回复
-
bug
难度 2/5 1-3 小时 新手友好度 76/100
johnsonjh/emu2-cpm86#68 · 1 条评论 ·
维护者通常 1 天内回复
-
Zenmap Crash未关闭Zenmap
难度 2/5 1-3 小时 新手友好度 68/100
维护者通常 2 天内回复
-
难度 2/5 1-3 小时 新手友好度 72/100
BasedHardware/omi#19306 ·
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 88/100
fastfetch-cli/fastfetch#2619 ·
维护者通常 1 天内回复