docs: compile the reference examples and inject them

[mvandeberg]

Nothing compiled the @code examples in the public headers, so broken examples reached readers. socket_option.hpp is typical. All 19 of its examples call set_option on a sock that no code declares.

Each example is now a tagged region in a file under test/doc/reference/. The file name comes from the symbol that the example documents. boost_corosio_doc_tests compiles these files. It uses the same warnings-as-errors settings as the page snippets. A Lua extension in doc/addons/extensions/ injects each region into the MrDocs corpus when the docs build runs. The reference then shows code that the build checked.

The two halves are independent. CI compiles the files even if the docs build does not run. The docs build injects the regions even if they do not compile.

A @par !example <tag> marker in the docstring gives the position of the example and the name of the region. The transform replaces the marker, so each example keeps its place and the page gets no new heading. A named region keeps two overloads in one file independent of each other.

Corosio also needs an ownership filter. Corosio depends on Capy, and MrDocs extracts Capy symbols into the corosio corpus. Capy headers hold 98 markers of their own, and the fail-closed guard reads them as examples that corosio cannot supply.

owned() skips a symbol in three conditions. Its extraction is dependency. Its docstring is a copy from a base class outside the corpus. Or its qualified name is not a corosio name. The second condition is necessary, because io_context::service has a corosio name and a Capy docstring.

MrDocs loads extensions only from
<install>/share/mrdocs/addons/extensions, and its addons-supplemental key has no effect. Therefore
doc/build_antora.sh installs the extension into a MrDocs, exports MRDOCS_ROOT, and writes it to GITHUB_ENV. This also moves the docs to the MrDocs develop channel, which the extension API needs. generate: becomes generator:. inaccessible-members and inaccessible-bases are gone, and the extract-private* defaults replace them. A diff against a pre-change baseline shows no other change.

The docs workflow searches the HTML for an example that only a reference file contains. This check is necessary, because a MrDocs without the extension renders no examples and still reports success. The paths filter now includes include/ and test/doc/reference/.

A coverage build skips the examples. No test runs them, and each one emits header template instantiations that no code calls. The CMake guard does this work, because every corosio coverage leg uses CMake. test/doc/Jamfile holds a parallel guard for a possible b2 coverage leg.

test/doc/CMakeLists.txt now has the warnings-as-errors settings that the Jamfile always had. It also links boost_corosio_openssl where CMake finds OpenSSL. The openssl_stream constructor template calls a non-inline member, and g++ leaves that member undefined at -O0.

Compilation alone cannot find some faults, and this change corrects them.

Three examples could never compile. The tcp_server restart sequence omitted ioc.restart(), and join() then blocked forever. The certificate-pinning example compared each chain certificate to one DER, so every handshake failed. Two examples held a passphrase in the source. The CRL examples set a revocation policy but left verification off.

Both TLS stream examples moved a socket into owning mode while a reference-mode stream pointed at it. Nine comments stated behaviour that the library does not have.

One header change is not documentation. The MSVC-4251 pragma in tls_context.hpp moves above the class docstring. MrDocs dropped that docstring while the preprocessor block was between the comment and the declaration.

19 @code blocks stay in the headers. 14 are on detail symbols that MrDocs does not publish. 5 are not C++: two ABNF grammars, two address strings, and one state diagram. 8 more examples compile but never render, because MrDocs stops with an assert on native_socket_option.hpp and publishes no symbol from it.

Closes #345

[cppalliance-bot]

An automated preview of the documentation is available at https://349.corosio.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-09-08 16:14:26 UTC

[cppalliance-bot]

GCOVR code coverage report https://349.corosio.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://349.corosio.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://349.corosio.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-09-08 16:27:11 UTC