ci: deny rustdoc warnings in lint-and-test#296
Merged
Conversation
Add a strict rustdoc pass (RUSTDOCFLAGS=-D warnings, --workspace --all-features --no-deps) to the lint-and-test job. Because buffa-test include!s codegen output (views, lazy views, json, reflect), this lints doc comments emitted by the code generator as well as hand-written ones, catching broken or private intra-doc links of the kind fixed in #295. Add a matching `task doc` so the gate is reproducible locally, fold it into `task verify`, and bump the job timeout to absorb the doc pass on a cold cache. No-Verification-Needed: CI/tooling-only change, no runtime surface
|
All contributors have signed the CLA ✍️ ✅ |
Give `task doc` a three-way protoc precedence: explicit $PROTOC, then .local/bin/protoc when present, then the system protoc. The .local binary (from install-protoc) lets buffa-test generate its edition 2024 protos — and thus lets rustdoc lint their generated docs — even when the system protoc is too old, matching what CI sees. Deliberately not `deps: [install-protoc]`: go-task evaluates preconditions even when a dep's status is satisfied, so that would make `task verify` demand gh auth on every run. The flags are command-line assignments rather than task-level `env:` because the OS environment outranks `env:` — an exported RUSTDOCFLAGS would silently drop -D warnings. No-Verification-Needed: Taskfile-only tooling change, no runtime surface
azdagron
approved these changes
Jul 10, 2026
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
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.
What this does
Adds a strict rustdoc gate to CI:
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-depsas a step in the existinglint-and-testjob (which already has the toolchain, protoc, and build cache it needs).Because
buffa-testinclude!s codegen output covering views, lazy views, json, and reflect configurations, documenting the workspace runs the intra-doc-link lints over generated doc comments as well as hand-written ones — so both warning classes fixed in #295 (public docs linking private items, and broken links emitted into generated lazy-view docs) are caught going forward.Also:
task doc— local mirror of the CI step, folded intotask verify, so the gate is reproducible before pushing.lint-and-testtimeout 10 → 15 minutes to absorb the doc pass on a cold cache.Depends on #295
Draft until #295 lands: the step fails on current
main(that PR fixes the existing warnings). Verified both directions locally:mainwithout docs: clean up rustdoc warnings #295: the step fails on thedecode_varint→decode_varint_packedprivate intra-doc link;cargo doccompletes cleanly across all 13 workspace crates, including buffa-test's generated modules.Coverage note
Workspace-excluded crates (
benchmarks/*, most ofexamples/*) are not documented, so generated code checked into those crates is outside this gate. The step comment says so explicitly.