docs: source duplicated reference snippets from the library itself - #388
Merged
mvandeberg merged 1 commit intoAug 27, 2026
Merged
Conversation
Several pages showed a library definition by keeping a hand-maintained copy of it in a snippet translation unit, free to drift from what ships -- and it had: cppalliance#383 changed IoAwaitable while both copies still showed the older one-requirement version. Closes cppalliance#381. Six definitions now carry tag::/end:: markers in their headers: Executor, ReadStream, WriteStream, IoRunnable, the two buffer sequence concepts and safe_resume. An antora.yml collector entry scans those headers into the examples tree, and ten include:: directives target the header instead of the snippet, so a page can no longer show a definition the library does not have. IoAwaitable is left out deliberately. cppalliance#383 replaced both of its code blocks with prose, so no page shows the concept and a marker would have no consumer. Each copy sat in a definition/concept_sketch namespace beside a pair of static_asserts, one against the copy and one against the real concept, under a comment claiming the two must match. The pair never established that: both hold whenever a single type satisfies both concepts, however far apart the definitions have drifted. The copies and the comments are gone, the asserts against the real concepts stay, and seven includes left unused by the deletions are removed. 9n's abbreviated WriteStream is replaced by the whole concept rather than pinned to it. A nested tag could only mark the opening lines; the elision marker and closing brace are not in the header, so the page would have to supply them as literal text, which doc-lint's B2 rule forbids. Showing all of it also serves the argument, since the page contrasts Capy's concept with Cobalt's concrete parameter and hiding half of Capy's requirements understates what the concept asks of a type. doc/lint/check-include-tags.mjs is new and blocking. Sourcing from headers removes the drift but leaves a quieter failure: Asciidoctor treats a missing include tag as a warning and exits 0, rendering an empty block, and the Antora CI leg only asserts that build/site exists because Antora also exits 0 on failure. A marker deleted during refactoring would empty a page with nothing going red. The check resolves every include::example$ directive through antora.yml's own scan config and fails on an unresolved file or a missing tag, across all 355 tagged includes rather than only the ten moved here. It stays outside the baseline/comparator posture the other lint steps share: it is a structural check, not a style rule with a backlog to burn down, and it stands at zero violations. The markers sit on their own line after the closing */ because MrDocs passes -fparse-all-comments, which merges a comment adjacent to a docstring into it.
|
An automated preview of the documentation is available at https://388.capy.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-08-26 18:53:12 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #388 +/- ##
===========================================
- Coverage 98.12% 98.09% -0.04%
===========================================
Files 65 130 +65
Lines 3314 6291 +2977
===========================================
+ Hits 3252 6171 +2919
- Misses 62 120 +58
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 66 files with indirect coverage changes Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
|
GCOVR code coverage report https://388.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-08-26 19:08:38 UTC |
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
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.
Several pages showed a library definition by keeping a hand-maintained copy of it in a snippet translation unit, free to drift from what ships -- and it had: #383 changed IoAwaitable while both copies still showed the older one-requirement version. Closes #381.
Six definitions now carry tag::/end:: markers in their headers: Executor, ReadStream, WriteStream, IoRunnable, the two buffer sequence concepts and safe_resume. An antora.yml collector entry scans those headers into the examples tree, and ten include:: directives target the header instead of the snippet, so a page can no longer show a definition the library does not have.
IoAwaitable is left out deliberately. #383 replaced both of its code blocks with prose, so no page shows the concept and a marker would have no consumer.
Each copy sat in a definition/concept_sketch namespace beside a pair of static_asserts, one against the copy and one against the real concept, under a comment claiming the two must match. The pair never established that: both hold whenever a single type satisfies both concepts, however far apart the definitions have drifted. The copies and the comments are gone, the asserts against the real concepts stay, and seven includes left unused by the deletions are removed.
9n's abbreviated WriteStream is replaced by the whole concept rather than pinned to it. A nested tag could only mark the opening lines; the elision marker and closing brace are not in the header, so the page would have to supply them as literal text, which doc-lint's B2 rule forbids. Showing all of it also serves the argument, since the page contrasts Capy's concept with Cobalt's concrete parameter and hiding half of Capy's requirements understates what the concept asks of a type.
doc/lint/check-include-tags.mjs is new and blocking. Sourcing from headers removes the drift but leaves a quieter failure: Asciidoctor treats a missing include tag as a warning and exits 0, rendering an empty block, and the Antora CI leg only asserts that build/site exists because Antora also exits 0 on failure. A marker deleted during refactoring would empty a page with nothing going red. The check resolves every include::example$ directive through antora.yml's own scan config and fails on an unresolved file or a missing tag, across all 355 tagged includes rather than only the ten moved here. It stays outside the baseline/comparator posture the other lint steps share: it is a structural check, not a style rule with a backlog to burn down, and it stands at zero violations.
The markers sit on their own line after the closing */ because MrDocs passes -fparse-all-comments, which merges a comment adjacent to a docstring into it.