Doc-quality validator (doc_lint.py) over the docs-JSON IR#1
Merged
Conversation
jturney
added a commit
that referenced
this pull request
Jun 3, 2026
The static `group: pages` (cancel-in-progress: true) put push-to-main and PR runs in the same group, so opening PR #1 cancelled main's in-flight docs run. Key the build concurrency by ${{ github.workflow }}-${{ github.ref }} so refs are independent (a newer push to the same ref still supersedes), and give the deploy job its own `pages-deploy` group with cancel-in-progress: false to serialize real deployments without killing one mid-flight. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Cross-checks each callable's parsed doc comment against its real signature, using only the existing --emit-cpp-docs-json output (no C++ changes): - @param / @tparam naming something the signature lacks -> error - a parameter/tparam left undocumented when siblings are -> warning - @return text on a void function -> warning - a malformed @throws with no exception type -> warning Diagnostics print as `file:line:col: severity: message [check]` (editor/CI parseable); exit is non-zero on any error (or any warning under --strict). --select runs a subset of checks; --format json for machine consumption. - scripts/doc_lint.py: the validator (stdlib only; installed via scripts/). - tests/: seeded-drift JSON fixture + golden + run_doc_lint.sh, registered as the apiary_doc_lint ctest (pure Python, needs no apiary binary). - ci.yml: add python so the ctest runs. - pages.yml: dogfood gate — lint apiary's own generated docs --strict (currently 0 findings) so doc drift can't regress. This is feature #2 from the Apiary tool-ideas list (doc-quality validator). The coverage ratchet half (baseline the --report-undocumented count, fail on increase) is a natural follow-on and is more naturally a consumer-side CI gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jturney
force-pushed
the
feature/doc-quality-validator
branch
from
abe35f4 to
133f450
Compare
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.
What
Adds
scripts/doc_lint.py— a doc-quality validator that cross-checks eachcallable's parsed doc comment against its real signature, using only the
existing
apiary --emit-cpp-docs-jsonoutput. No C++ changes: the IR alreadycarries
params/template_params/return_typeplus the parsed@param/@tparam/@return/@throws, so this is a pure-Python checker overthe JSON.
This is feature #2 from the Apiary tool-ideas list — turning documentation
drift into a CI gate instead of something discovered at render time.
Checks
unknown-param/unknown-tparam@param/@tparamnames something the signature doesn't have (typo/renamed/removed)missing-param/missing-tparamreturns-on-void@returntext on avoidfunctionmalformed-throws@throwswith no exception typeDiagnostics print as
file:line:col: severity: message [check](editor/CIparseable); exit is non-zero on any error (or any warning under
--strict).--selectruns a subset;--format jsonfor machine consumption. Handlesnested classes, constructors, and function-like macros.
Tests / CI
run_doc_lint.sh, registered as theapiary_doc_lintctest (pure Python — needs no apiary binary).ci.yml: addpythonso the ctest runs.pages.yml: dogfood gate — lint apiary's own generated docs--strict(currently 0 findings), so doc drift can't regress.
Packaging
doc_lint.pylives inscripts/, which the recipe already installs, soconsumers get
share/apiary/scripts/doc_lint.pyto run over their own JSON.Follow-on (not in this PR)
The coverage ratchet half (baseline the
--report-undocumentedcount, failCI on increase). Undocumented entities aren't in the docs-JSON (the docs filter
requires a comment), so the ratchet needs the tool's stderr count — and it's
more naturally a consumer-side gate.
🤖 Generated with Claude Code