Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#1,269 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
c
Ambito
developer-experience, documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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).

Lingua principale
C
Stelle
3
Fork
7
Merge medio
4h 15m
PR unite (30g)
106

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di InauguralSystems/EigenScript

Tutte le issue di InauguralSystems/EigenScript

Issue simili

Altre issue su C

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.