docs: give doc code one shared header and one namespace style - #390
Conversation
Every file under test/doc/ opened with the same 24-line warning-suppression preamble -- 105 copies of it, byte for byte -- and most carried both `namespace capy = boost::capy;` and `using namespace boost::capy;`, where the directive supersedes the alias and makes the alias dead text. The preamble now lives in test/doc/doc_warnings.hpp, included once per file outside every tag:: region. Three files kept a warning of their own, each under a comment saying why. The using-directives are gone and every capy name in a doc fragment is spelled capy::, so a reader can tell which names in an example come from the library. example/ already read this way; test/doc now matches it. -Werror does not finish this conversion on its own: write, read, when_all, when_any, run_async and the make_buffer overloads are ordinary free function templates, so ADL keeps finding them unqualified once a call has a capy-typed argument. Those were found by sweeping the tree against the symbol list MrDocs publishes, not by the compiler. A second class the compiler cannot see is the using-declaration -- `using capy::task;` in scaffolding feeds a bare name into a tagged region that renders on a page; nine of those are gone too. Eight fragments rendered a using-directive on the site; those show the alias instead. The inline pseudocode blocks on 7a.drivers, 4b.launching and 5a.buffers contradicted the fragments beside them and are qualified to match. make_error_code was spelled three ways across the docs and now names its owner at every call site. Blocks that verbatim-quote library-internal source keep that source's own unqualified spelling, since inside namespace boost::capy that is what the library actually says. The convention is recorded in doc/STYLE_GUIDE.md as B5, enforced by review only -- no gate. Closes cppalliance#387
|
An automated preview of the documentation is available at https://390.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-27 16:10:37 UTC |
|
GCOVR code coverage report https://390.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-08-27 16:23:57 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #390 +/- ##
===========================================
+ Coverage 98.09% 98.14% +0.04%
===========================================
Files 130 130
Lines 6291 6291
===========================================
+ Hits 6171 6174 +3
+ Misses 120 117 -3
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
2 participants
Every file under test/doc/ opened with the same 24-line warning-suppression preamble -- 105 copies of it, byte for byte -- and most carried both
namespace capy = boost::capy;andusing namespace boost::capy;, where the directive supersedes the alias and makes the alias dead text.The preamble now lives in test/doc/doc_warnings.hpp, included once per file outside every tag:: region. Three files kept a warning of their own, each under a comment saying why.
The using-directives are gone and every capy name in a doc fragment is spelled capy::, so a reader can tell which names in an example come from the library. example/ already read this way; test/doc now matches it.
-Werror does not finish this conversion on its own: write, read, when_all, when_any, run_async and the make_buffer overloads are ordinary free function templates, so ADL keeps finding them unqualified once a call has a capy-typed argument. Those were found by sweeping the tree against the symbol list MrDocs publishes, not by the compiler. A second class the compiler cannot see is the using-declaration --
using capy::task;in scaffolding feeds a bare name into a tagged region that renders on a page; nine of those are gone too.Eight fragments rendered a using-directive on the site; those show the alias instead. The inline pseudocode blocks on 7a.drivers, 4b.launching and 5a.buffers contradicted the fragments beside them and are qualified to match. make_error_code was spelled three ways across the docs and now names its owner at every call site.
Blocks that verbatim-quote library-internal source keep that source's own unqualified spelling, since inside namespace boost::capy that is what the library actually says.
The convention is recorded in doc/STYLE_GUIDE.md as B5, enforced by review only -- no gate.
Closes #387