RDoc

Our Ruby gems document every class and method in the source, and each release tag publishes the RDoc built from it under /rdoc/. The table below always shows the newest published version. Go modules do the same with Go doc.

Published gems

Each gem keeps its ten newest versions; /rdoc/bbs/latest/ and /rdoc/warp_engine/latest/ always point at the newest one, and the version picker at the top of every page switches between them.

The rule: 100% documented

Both repos say it in their CLAUDE.md, and CI enforces it: a push fails when rdoc -C reports anything below 100%. Every class, module, constant, attribute and public or protected method gets an RDoc comment directly above it that says what it does, what it takes, what it returns, what it raises and what it changes. The why of a change goes into the commit, not the comment.

• RDoc markup, not Markdown or YARD: +word+, tt tags for several words, *bold*, _emphasis_, labelled lists for arguments, examples in an indented block.
• No :nodoc: to reach the number; a helper that is not part of the API becomes private instead.
• In the teletypegames monorepo the no-comments rule still holds inside method bodies; the RDoc comment above a definition is the one exception, and only under libs/ruby/warp_engine.

How it gets here

1. A release tag runs the gem's pipeline: tests, the coverage gate, then rdoc builds the HTML and a meta.json (version, commit, date, coverage).
2. The pipeline uploads rdoc.tar.gz as the Gitea generic package named after the gem with an -rdoc suffix, in the engines org.
3. Gitea's package webhook calls the wiki-fetcher (/rdoc-hook), which also checks every ten minutes. It unpacks the new version, links in the wiki look, moves latest and rewrites /rdoc/index.json.
4. The table above reads that index in the browser, and the engine pages link the latest reference, so no wiki page has to be edited for a release.

The wiki-fetcher's /health turns red when an RDoc round fails. Details: fetcher/README.md in services/wiki-pages.

Writing docs locally

rdoc -C lib                                   # rubbs: coverage, lists what is missing
rdoc -C -x templates app lib                  # warp_engine
rdoc -o /tmp/doc --main README.md lib README.md && open /tmp/doc/index.html

Use the same RDoc version as CI (8.1.0, gem install rdoc -v 8.1.0): older versions count attributes and namespaces differently.