Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

docs: generate STDLIB.md / BUILTINS.md from structured doc-comments instead of hand-writing them

オープン
  • 何か問題がありますか？
#1,269 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
45/100
issue の種類
ドキュメント
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
c
領域
developer-experience, documentation

調査の方向性

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 の本文から書いたものです。

説明

area:docs kind:decision

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.

  1. A structured doc-comment convention for lib/*.eigs public functions (signature, one-line summary, args, return, an example that runs), documented in docs/STDLIB.md's preamble or CONTRIBUTING.
  2. A C-side description for every builtin at its registration site (where eigenscript --api already enumerates the surface).
  3. 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.
  4. The drift gate becomes "regenerate and diff": a new function without a doc-comment fails by name, and so does an edited generated region.
  5. 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).

Done when

  • Decision recorded in a comment here: generate the API reference from source (structured doc-comments in lib/*.eigs + a description at each builtin's C registration site, with a generator writing the tables of docs/STDLIB.md and docs/BUILTINS.md), or keep hand-written tables guarded by the existing tools/stdlib_index_check.sh drift gate. Name the chosen option and why.
  • If adopted: the doc-comment convention (signature, one-line summary, args, return, a runnable example) is written in docs/STDLIB.md's preamble or CONTRIBUTING, and every public lib/*.eigs function and every builtin eigenscript --api lists carries one.
  • If adopted: a generator in tools/ runs in CI, and the generated regions of docs/STDLIB.md and docs/BUILTINS.md are byte-identical to its output; prose outside the fenced generated regions stays hand-written. Planted once: a new function with no doc-comment fails by name, and a hand edit inside a generated region fails.
  • If adopted: the examples taken from doc-comments run under tests/test_doc_examples.py, and the executed count printed by that test goes up by the number of extracted examples.
  • If rejected: close with the reason, and state which gate keeps STDLIB.md/BUILTINS.md honest instead.
主要言語
C
スター
3
フォーク
7
平均マージ
4時間 7分
マージ済み PR（30日）
112

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

InauguralSystems/EigenScript のほかの issue

InauguralSystems/EigenScript の issue をすべて見る

似ている issue

C の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。