RDoc

Ruby gemjeink minden osztályt és metódust a forrásban dokumentálnak, és minden kiadási tag közzéteszi az ebből épült RDoc-ot a /rdoc/ alatt. Az alábbi táblázat mindig a legfrissebb kiadott verziót mutatja. A Go-modulok ugyanezt a Go doc-kal csinálják.

Kiadott gemek

Gemenként a tíz legújabb verzió marad meg; a /rdoc/bbs/latest/ és a /rdoc/warp_engine/latest/ mindig a legújabbra mutat, és minden oldal tetején a verzióválasztóval lehet váltani köztük.

A szabály: 100% dokumentált

Mindkét repó CLAUDE.md-je kimondja, és a CI ki is kényszeríti: a push elbukik, ha az rdoc -C 100% alatti értéket mutat. Minden osztály, modul, konstans, attribútum és publikus vagy protected metódus közvetlenül fölötte RDoc-kommentet kap arról, hogy mit csinál, mit kap, mit ad vissza, mit dob és mit változtat meg. A változtatás oka a commitba megy, nem a kommentbe.

• RDoc-jelölés, nem Markdown vagy YARD: +szó+, tt-tag több szóhoz, *félkövér*, _kiemelés_, címkés lista a paraméterekhez, példa behúzott blokkban.
• Nincs :nodoc: a szám kedvéért; ami nem része az API-nak, az private lesz.
• A teletypegames monorepóban a metódustörzsekben továbbra is él a komment nélküli szabály; a definíció fölötti RDoc-komment az egyetlen kivétel, és csak a libs/ruby/warp_engine alatt.

Hogyan kerül ide

1. A kiadási tag lefuttatja a gem pipeline-ját: tesztek, lefedettségi kapu, majd az rdoc megépíti a HTML-t és egy meta.json-t (verzió, commit, dátum, lefedettség).
2. A pipeline feltölti az rdoc.tar.gz-t Gitea generic csomagként az engines orgba, a gem nevén -rdoc végződéssel.
3. A Gitea csomag-webhookja meghívja a wiki-fetchert (/rdoc-hook), amely tízpercenként magától is ránéz. Kicsomagolja az új verziót, ráteszi a wiki arculatát, átállítja a latest-et és újraírja a /rdoc/index.json-t.
4. A fenti táblázat a böngészőben olvassa ezt az indexet, a motoroldalak pedig a latest címre linkelnek, így kiadáskor egy wikioldalt sem kell szerkeszteni.

Ha egy RDoc-kör elbukik, a wiki-fetcher /health-je piros lesz. Részletek: fetcher/README.md a services/wiki-pages-ben.

Dokumentálás helyben

rdoc -C lib                                   # rubbs: lefedettség, kilistázza, mi hiányzik
rdoc -C -x templates app lib                  # warp_engine
rdoc -o /tmp/doc --main README.md lib README.md && open /tmp/doc/index.html

Ugyanazt az RDoc-verziót használd, mint a CI (8.1.0, gem install rdoc -v 8.1.0): a régebbiek másképp számolják az attribútumokat és a névtereket.