2. Documentation is enforced by CI

• Status: Accepted
• Date: 2026-09-02

Context

Korrin's non-negotiable requirement is thorough documentation that never goes stale. Documentation that is merely encouraged rots: it drifts from the code, nobody trusts it, and eventually nobody reads or updates it. The only reliable way to keep docs honest is to make the build fail when they are wrong or missing.

There are three distinct things to keep honest:

1. API documentation — every public item has a doc comment.
2. The language specification — its described behaviour matches the implementation.
3. Design rationale — every meaningful decision has an ADR.

Decision

CI enforces all three:

1. API docs. Every crate sets #![warn(missing_docs)] and CI builds with RUSTFLAGS=-Dwarnings and runs cargo doc, so a missing doc comment or a broken intra-doc link fails the build. Module headers must explain purpose and rationale, not just restate the module name.
2. Specification. Every runnable code block in docs/spec/ is tagged and extracted by a test harness (crates/korrin/tests/spec.rs), executed, and its output compared against the block's declared expected output. A spec example that lies fails CI. A companion test asserts every registered builtin is documented in docs/spec/08-builtins.md.
3. ADRs. A test checks that every file in docs/decisions/ is linked from the index and contains the required sections.

Additionally: doc examples on public API are real cargo test doctests, a link checker runs over docs/, and the PR template carries a docs checklist.

Consequences

• Changing behaviour requires updating the spec in the same change, or CI goes red. This is the point.
• The spec harness needs the interpreter to be embeddable and output-capturing ([korrin::run]). That shaped the library API — a good outcome.
• Slightly slower CI. Worth it.
• Writing a new public function means writing its doc comment before it merges. Treated as part of "done", like tests.

Alternatives considered

• Convention and code review only. This is the default that fails everywhere. Reviewers miss things; standards slip under deadline pressure.
• A separate docs site maintained by hand. Guaranteed to drift from a fast-moving implementation.
• Doc coverage as a non-blocking metric. A number nobody is forced to act on is a number that goes down.