Repository navigation
Close the scribble coverage gap and make documentation drift fail CI - #232
Merged
Merged
Conversation
Documentation rots when nothing checks it. Two moves, paired: Coverage: document every public export that had no manual entry — the whole RVT1 framing and value-codec surface (rivet/protocol: frame struct, read/write, encode/decode, transport limits, message-type constants), application resources (rivet/resources), current-rivet-diagnostic-sink, install-crash-hook!, the SemVer predicates, the Ed25519 key/digest/base64 primitives, canonical manifest payload helpers, verify-update-artifact!, make-install-plan, current-install-kind, and the updater? predicate whose absence produced the manual's one undefined-tag warning. Contracts are taken from the module sources, not invented. Anti-rot guards in the docs suite: the CI-guide version pin is derived from info.rkt so a release that forgets docs/ci*.md goes red (the old check hardcoded v0.8.0 and passed forever against a stale guide), and scribble coverage is checked in both directions — an export without a manual mention fails, and a manual entry for a removed binding fails. defstruct* forms synthesize their constructor, predicate, structure-type binding, and accessors exactly as the rendered output covers them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Library docs rot silently: a new export lands without a manual entry, a release forgets to bump the pinned version in the guides, a rename leaves stale entries behind — and every check stays green because nothing compares docs to reality. This PR closes the current gap and installs the guards that keep it closed.
What
Coverage — every public export now has a manual entry, contracts taken from the module sources:
rivet/protocolwas a fully public module with zero documentation (frame struct, read-frame/write-frame, encode-value/decode-value, the four transport limits, all seven message-type constants).rivet/resources.version<?throughversion>?), the Ed25519 key/digest/base64 primitives,manifest-schema-version+manifest->payload-bytes/payload-bytes->manifest,verify-update-artifact!,make-install-plan,current-install-kind.current-rivet-diagnostic-sink(with the embedded-console rationale),install-crash-hook!,updater?(its absence was the manual's one undefined-tag warning; render is now warning-free).Anti-rot guards (tests/documentation.rkt):
docs/ci*.mdpin check derives the expected tag frominfo.rktrelease-version. The previous check hardcoded v0.8.0, so it kept passing while the guide went stale — the guard itself was enforcing rot. Guides bumped to v0.8.1.defstruct*forms synthesize constructor/predicate/struct:/accessors exactly as the rendered output covers them, mirroring rendered-HTML verification), and adefproc/defthing/defform/defparamentry for a binding that is no longer exported fails.Testing
raco test tests/documentation.rkt560 passed,tests/public-api.rkt9 passed,raco setuprenders the manual with zero undefined-tag warnings, and rendered HTML spot-checks confirm the new sections are live (arrow/angle identifiers verified via their HTML-escaped forms).