doc: document macros with MrDocs - #83
Open
jll63 wants to merge 33 commits into
Open
Conversation
MrDocs now extracts `#define` directives as symbols (cppalliance/mrdocs#1192), so the macro reference no longer has to be written by hand. Move the content of the sixteen hand-written BOOST_OPENMETHOD*.adoc pages into doc comments on the macros themselves, and delete the pages. `ref_macros.adoc` stays as the curated basic/advanced index, now pointing at the generated reference pages. Two macros needed restructuring to have a single documented definition: * BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS is only ever tested, never defined by the library, so there was no directive to extract. Add a documentation-only `#define` under `__MRDOCS__`, after `default_registry`, so documenting it cannot change what it documents. * BOOST_OPENMETHOD_EXPORT_REGISTRY and BOOST_OPENMETHOD_INSTANTIATE_REGISTRY had one definition per ABI. Move the per-platform bodies into BOOST_OPENMETHOD_DETAIL_* macros so the public macros are defined - and documented - once. Rename the macro parameters NAME and ARGS to ID and PARAMETERS. The generated synopsis prints the real parameter names, and the prose has always called them ID and PARAMETERS. Convert the {{MACRO}} placeholders in doc comments to `@ref MACRO`, which MrDocs resolves to a proper xref, and retarget the guide pages' xrefs at the generated pages. This removes two perl substitutions from build_antora.sh: the one that rewrote {{MACRO}} into a hand-built relative link, and the {{BASE_URL}} pass over the macro pages, which MrDocs now handles itself via base-url. Requires a MrDocs new enough to support macros; an older one silently produces no macro pages, which breaks the reference xrefs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
An automated preview of the documentation is available at https://83.openmethod.prtest3.cppalliance.org/libs/openmethod/doc/html/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-08-02 19:05:02 UTC |
MrDocs escapes prose punctuation but emits markdown-link targets verbatim, so a
literal Antora resource ID survives a doc comment: the link
[Shared Libraries](xref:ROOT:shared_libraries.adoc)
comes out as `xref:ROOT:shared_libraries.adoc[Shared Libraries]`, which Antora
resolves from the reference module to the component's ROOT module. Use it on
all three registry-sharing macro pages, in place of the plain-text "see the
Shared Libraries section of the documentation" that assumed the xref could not
survive.
The link must be on one line: MrDocs parses it after the comment has been split
into lines, and a link broken across two `//!` lines falls through as escaped
literal text. That is what happened to the two [CRTP mixin] links in
inplace_vptr.hpp, which render today as
[CRTP] mixin](https://en.wikipedia...)
Shorten their text to [CRTP] so the link fits on one line inside the column
limit, and move `mixin` into the surrounding prose.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #83 +/- ##
===========================================
- Coverage 94.34% 94.31% -0.03%
===========================================
Files 43 88 +45
Lines 2916 3325 +409
Branches 0 1579 +1579
===========================================
+ Hits 2751 3136 +385
+ Misses 165 158 -7
- Partials 0 31 +31
... and 9 files with indirect coverage changes Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
Every guide page links into the reference; nothing linked back out. Give each macro page a See Also section pointing at the guide that covers it, using the markdown-link-to-Antora-xref form established in the previous commit. `@see` is the right vehicle: MrDocs renders `symbol.doc.sees` under a "See Also" heading, each entry through the same inline path as description text, so a markdown link works there. Link text matches the nav labels, and a symbol is linked to a guide page only where that page actually discusses it - so BOOST_OPENMETHOD_OVERRIDERS points at Header and Implementation Files (overrider containers) while BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS points at Registries and Policies. The three registry-sharing macros move their inline guide link into See Also, so all the macro pages have the same shape. Only macro pages get these links. MrDocs writes `:relfileprefix: ../../` into its nested reference pages - by design, its template says so - and Asciidoctor prepends that to the xref target Antora resolves, so `xref:ROOT:basics.adoc` arrives as `../../ROOT:basics.adoc` and does not resolve. Macro pages sit at the reference module root, get no prefix, and work. Clearing the attribute fixes the nested pages but breaks ~1250 breadcrumb links, because the `boost::openmethod::` xrefs in the document title bypass Antora's resolver and genuinely need it. To be reported upstream: the title partial should inline the prefix itself rather than rely on a document attribute that corrupts module-qualified xrefs. Also turn three dead `@see` entries into real references: `@see indirect_vptr.` rendered as escaped plain text, and two `@see The main template for documentation.` had nothing to click. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ref_headers.adoc linked each public header to its source through `{{BASE_URL}}`,
which is not an AsciiDoc construct. Asciidoctor saw the inner `{BASE_URL}`,
found no such attribute and - under Antora's default `attribute-missing: skip` -
left the text alone, so the literal `{{BASE_URL}}` reached the HTML and
build_antora.sh rewrote it with perl after the site was built.
That cost 17 "skipping reference to missing attribute" warnings on every build,
indistinguishable from real ones, and left local builds with 17 broken links:
BASE_URL is only computed when a CI environment is detected, so outside CI the
perl step never ran.
Use `link:{base-url}/...` instead, give antora.yml a fallback pointing at
master - matching the one already in mrdocs.yml, which serves the same purpose
for the generated reference - and have build_antora.sh pass
`--attribute base-url=...` when it can determine the commit. A command-line
attribute outranks the component descriptor, so the exact commit still wins in
CI. The perl rewrite is gone.
The mrdocs.yml patch-and-restore stays: that base-url is MrDocs configuration
rather than an AsciiDoc attribute, and the reference extension builds a fixed
MrDocs argument list with no hook to inject one.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
List the stock policies in the order a registry declares them, so the table reads the same way as `default_registry`: type_hash before vptr. Drop the "This section discusses" preamble from the shared libraries page and state the fact directly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The See Also sections added in b2dcdb8 stopped at the macro pages. The other 52 links, on the C++ symbol pages, had to be dropped: MrDocs sets `:relfileprefix: ../../` on nested pages, Asciidoctor folds it into the xref target Antora resolves, and `../../ROOT:basics.adoc` is not a valid resource id. Clearing the attribute is not an option - it breaks ~1250 breadcrumb links, because the xrefs in the document title bypass Antora's resolver and need it (cppalliance/mrdocs#1245). Override `markup/a.adoc.hbs` instead, through `addons-supplemental` - the documented way to replace a few templates while falling back to the built-ins for the rest. The new branch recognises an `xref:ROOT:` href and, on a nested page, emits a `link:` rather than an `xref:`. A link macro is not an inter-document xref, so relfileprefix never touches it; `relfileprefix` reaches the reference module root and the guide sits one level above it, hence the extra `../`. At the root the href is passed through unchanged, so the macro pages keep emitting real xrefs and Antora still validates them. Everything else in the file is upstream verbatim, so it diffs cleanly against a newer MrDocs, and the header comment says when to delete it. With that in place, restore the 52 links: the error types and policy categories in preamble.hpp, the smart-pointer traits and aliases in interop, the stock policies, `method`, `use_classes` and `virtual_ptr` in core.hpp, `initialize` and `finalize`, and the two inplace_vptr mixins. 73 guide links now render across 65 reference pages, at depths 0, 2 and 3. The whole-site link check is unchanged at 19 broken links, all of them the `file://` edit-page links a local build always produces - in particular the breadcrumbs are intact, which is what the earlier attempt at clearing relfileprefix broke. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The built-in see-also partial renders each @see entry through `doc/block/see`, i.e. as a block, and MrDocs separates blocks with a blank line - which AsciiDoc reads as a paragraph break. A symbol with several @see entries therefore got a paragraph each, one link per line. Override the partial to render the entries inline instead. `doc/inline-container` is what `doc/block/see` reaches through `doc/block/paragraph`, so going straight to it drops the block separation; the entries are then joined with ", " and the whole list is one paragraph. The blank line before the section closes keeps the page footer out of it. Four @see entries were sentences rather than bare references, which a comma join would have read as "... for data members., Error Handling". Move the clause into the description, where it is more visible anyway, and leave the reference bare: no_overrider and ambiguous_call pointing at bad_call, the policies namespace pointing at registry, and inplace_vptr_derived pointing at inplace_vptr_base. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The base-url MrDocs puts behind every "Declared in <header>" link comes from mrdocs.yml, and the Antora extension invokes MrDocs with a fixed argument list, so pointing it at the commit means editing the file in place. The restore ran at the end of the script, which `set -e` skips: a build that failed anywhere after the edit left mrdocs.yml patched, and the next run then copied the patched file to mrdocs.yml.bak and restored that - losing the original base-url for good. Move the restore into an EXIT trap armed right after the backup is taken, so it runs whether the build succeeds or aborts. Paths are absolute so the trap does not depend on the working directory at exit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It was the only bare label in the navigation with somewhere obvious to point: the reference module's index page, which lists the namespaces and the macros. "Basic Features" and "Advanced Features" stay labels, having no page of their own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A paragraph of a doc comment reading
include:<path>[#<tag>[;<tag>...]]
is now replaced by the file, or its `// tag::name[]` regions, rendered as
a code block. The point is that the example on a reference page is a
region of a file the build compiles and runs, so it cannot drift from the
library without a build failing.
Implemented as a MrDocs corpus transform in Lua, per Alan de Freitas'
suggestion. Regions are selected in file order the way Asciidoctor's
`tags=` attribute selects them, and each contiguous run is dedented on its
own before the runs are joined, so a snippet can draw its setup from
namespace scope and its body from inside a test case and still render
flush. A missing file or unknown tag aborts the build naming both.
The transform rebuilds a comment's whole block list rather than patching
the marker in place, because three gaps in the 0.8.0 extension API leave
no alternative: array proxies expose no indexed write to Lua, proxies read
out of the corpus are rejected as setter input, and `level` is refused by
the generic setter. The header comment records all three; if they are
fixed upstream the script collapses to a few lines.
Snippets live in doc/modules/ROOT/snippets, which Antora ignores as an
unrecognised family, and are built and run with the examples -- Boost
keeps tests under test/.
Converts two `virtual_ptr` examples, both of which were broken:
- `operator=(std::nullptr_t)` had a mangled opening fence written after
the body, so the example rendered as escaped prose run onto one line,
trailed by a stray `//!` and an empty code block.
- `cast()` had an empty `@code`/`@endcode` pair.
Generating the reference over the whole corpus produces byte-identical
output apart from those two pages, so the block-list rebuild is lossless.
Replaces the 24 remaining `@code` blocks in core.hpp with markers into doc/modules/ROOT/snippets/virtual_ptr.cpp, which the build compiles and runs. core.hpp now has no `@code` left. A marker names a class-setup tag only where the example deviates from the norm -- that is, where it relies on non-polymorphic classes, which is the point of those examples. The other markers render the body alone, since repeating four lines of Animal/Dog on every page is noise. Deletes test/test_virtual_ptr_doc.cpp. Its only purpose was to compile these examples a second time, by hand, with nothing keeping the two copies in step; the snippets do that job now. Both build systems glob, so no build file changes. Note that b2 builds only test/, so it no longer compiles these examples at all -- adding a Jamfile for the snippets would route them back through the test build we just moved them out of. Two examples were attached to the wrong overload: the assignment operators briefed "from a (const) smart pointer" and "move-assign from a smart pointer" both showed assigning from a *virtual* pointer, which is what the following two overloads document, with near-identical bodies. They get bodies that assign from a bare std::shared_ptr, matching their briefs. Being compiled from now on, they cannot drift again. A third malformed block is fixed by the conversion: the smart-pointer default constructor had a stray `@par Example` inside its `@code` fence. Generating the reference produces exactly 20 changed pages -- 24 blocks less the four that share a doc comment with another -- and no other difference across the 353 generated files.
The constructor from another `virtual_ptr` introduced its examples with "Assigning from...", though it documents a constructor. Both that comment and the assignment one prepended the non-polymorphic class setup to two consecutive examples, so the same five lines rendered twice on one page. Only the first names the setup tag now. Also backticks `virtual_ptr` in those lines: unformatted, it rendered as escaped text beside the correctly formatted mention in the third paragraph of the same section.
Two gaps: the 13 examples on the `virtual_ptr<SmartPtr>` specialization were all `std::shared_ptr`, and the three interop headers had no examples at all -- `unique_virtual_ptr`, `make_unique_virtual` and the `virtual_traits` specializations were documented in prose only. Adds unique_ptr examples to the four move overloads of `virtual_ptr<SmartPtr>`, alongside the shared_ptr ones, plus a static_assert on the copy constructor recording that a move-only smart pointer cannot be copied from. Those five are where the two pointer flavours actually diverge; copying an example that only differs in the pointer type would not earn its place on the page. Adds snippets/smart_pointers.cpp and snippets/intrusive_ptr.cpp, and markers on all three interop headers: each `virtual_traits` specialization now shows a method declared with that smart pointer as a virtual parameter, and each alias and factory shows a use. The by-reference specializations show what the by-value ones cannot -- that passing by const reference does not bump the reference count. Grouped two files rather than three: shared_ptr and unique_ptr share a class hierarchy, while intrusive_ptr needs an intrusive_ref_counter base. 16 reference pages change, and no others.
`make_shared_virtual`, `make_unique_virtual` and `make_boost_intrusive_virtual` showed the returned pointer's vptr rather than what the pointer is for. Each now dispatches a call. Each needs a method taking a `virtual_ptr` to the smart pointer, which is a different signature from the by-value and by-reference ones already in the files, hence the extra namespaces. The unique version reads `poke(std::move(animal))`: the pointer is move-only, so passing it to a method consumes it. That is worth showing on the page rather than hiding behind a temporary.
The eight policies headers documented registry composition entirely in prose. policies/static_rtti.hpp was worse than empty: its example read `TODO` followed by `include::example$static_rtti.cpp[tag=all]`, a tag that does not exist -- examples/static_rtti.cpp uses Quickbook `//[ all` markers, not Antora ones -- so the page shipped a broken instruction. Adds snippets/policies.cpp, one registry per policy since policies are registry-level and several are mutually exclusive, and snippets/static_rtti.cpp, which needs its own translation unit because the policy has to be selected before <boost/openmethod.hpp> is included. The tagged region is usually the registry declaration, because that is the line a user writes; the classes, method and assertions around it are compiled but untagged, so the rendered snippet stays short while the whole thing is verified. Writing them turned up a constraint the reference understates. Composing `std_rtti` with `vptr_vector` and no `type_hash` throws `std::bad_alloc` on the first `initialize()`: the vector is indexed by the type id, and `std_rtti` makes a type id a pointer, so it is sized to the address space. The `fast_perfect_hash` example now says so. Also drops a stray `@ref` from stderr_output.hpp's brief, which was rendering "Writes" as a broken code reference on that page and on the three listing pages that repeat the brief.
preamble.hpp's four error examples and the accompanying fix, plus the programs in initialize.hpp and inplace_vptr.hpp, now come from compiled snippets. What is left is pseudo-code and stays: macros.hpp's eight synopses, and the DLL incantation in preamble.hpp and default_registry.hpp, which shows IMPORT and EXPORT of one registry together and so cannot compile in a single translation unit. The four error examples live in one snippets/errors.cpp, each in its own registry so that one deliberate mistake does not mask another. That needs a marker policy carrying an integer: registries deriving from the same `registry<...>` specialization share one state, so a single alias would have pooled the registrations -- the same device, and the same reason, as `test_registry_` in test/test_util.hpp. Compiling them showed the first example did not demonstrate its own error. It registered `Animal`, the method's virtual parameter, and left an unused `Dog` unregistered; that raises nothing. What raises `missing_class` is the reverse -- registering `Dog` and leaving `Animal` unregistered -- so the example now does that. The markers also needed a blank `//!` line above them. The `@code` fence used to end the preceding paragraph; without it the marker would have been swallowed into the prose line above and never matched.
A registry's identity is the `registry<Policy...>` specialization: state, class and method lists, dispatch tables and `static_vptr` are all keyed on it. Two structs deriving from the same specialization are therefore one registry, sharing everything. Nothing said so. The guide said only to derive a class rather than typedef, which invites exactly the wrong conclusion -- that the class is the registry. Writing snippets/errors.cpp ran straight into it: four registries derived from one alias pooled their registrations, so three of the four error examples silently stopped raising their error. The trap is worst in a case the library recommends, isolating one set of methods from another: two such registries would naturally carry the same policies and so would silently be one. The way out is to give each a policy of its own, which is what test_util.hpp's `test_registry_` does and what snippets/errors.cpp had to reinvent. Both are now documented. The example is a `static_assert` on `registry_type`, which states the rule exactly and cannot go stale. It lives under examples/ rather than snippets/ because the guide reaches it with `include::example$`, which cannot see snippets/ -- Antora ignores the directory as an unrecognised family. The reference markers point at the same file, so there is one copy.
macros.hpp had eight @code blocks and not one of them showed how to use a macro: they are all synopses of what the macro expands to, under Implementation Notes. The page explained dispatch semantics precisely and never declared a method. Adds snippets/macros.cpp, one file for the macro family so the rest can add tags to it, and a marker on BOOST_OPENMETHOD placed above Implementation Notes so usage comes before internals. The rendered example is the declaration and two calls, nothing else. The classes, the registration, the overriders and initialize() are in the file but outside the tags -- overriders belong on the BOOST_OPENMETHOD_OVERRIDE page, and the `// hiss` and `// bark` comments already tell the reader they exist. The calls write to std::cout, which on its own proves nothing, so the snippet redirects std::cout to an ostringstream and checks what came out. Both the redirect and the BOOST_TEST sit outside the tagged region, so the page shows the idiomatic printing form while the build verifies that dispatch really picks the two overriders.
Tags the two overriders already in snippets/macros.cpp and points the macro at declare;override;call, so the page shows the method declaration for context, both overriders, and the calls they answer -- the same example BOOST_OPENMETHOD renders, with the overriders no longer elided. Placed above Implementation Notes, matching BOOST_OPENMETHOD.
…at it The two pages were rendering overlapping halves of one example. Now BOOST_OPENMETHOD's Example section is a link to BOOST_OPENMETHOD_OVERRIDE's, which shows the declaration, both overriders and the calls -- a method declared with nothing overriding it was the less useful half anyway. The link is a markdown link whose target is an Antora resource ID with a fragment, which the markup/a template emits verbatim; Antora resolves it to BOOST_OPENMETHOD_OVERRIDE.html#_example. Macro pages sit at the reference module root, so no relfileprefix is in play. snippets/macros.cpp is unchanged: the `declare` and `call` tags are still rendered, now only through the overrider page.
Four registrations of the same hierarchy - Cat and Dog under Animal, Bulldog under Dog - showing what does and does not describe the inheritance. All four were run before being written down. The two that work: one call listing everything, or several calls where each class appears alongside its direct bases, `Dog` repeated to attach `Bulldog` to it. The two that do not differ in how they fail. Registering one class per call describes no inheritance and initialize reports missing_base. But listing a class with an ancestor in place of its direct base - `(Animal, Bulldog)` when Bulldog derives from Dog - is accepted: initialize succeeds, and a call passing a Bulldog quietly runs the overrider for Animal rather than the one for Dog. That silence is what makes it worth a paragraph. These stay as @code. They are contrasting registrations of one hierarchy, two of them wrong on purpose, so a compiled snippet would have to be four translation units to say what four blocks say plainly. Also reorders the macro table in ref_macros.adoc to declare, override, register rather than alphabetically.
Points the macro at the rolex_3 example, which is the case the macro exists for, already compiled and run and already tagged: roles.hpp declares `pay` and supplies a default overrider that three translation units include, and salesman.cpp adds a more specialized one. The second block is what makes the first legible -- it shows the specialized overrider using plain BOOST_OPENMETHOD_OVERRIDE, because it is defined once, and reaching the header's overrider through BOOST_OPENMETHOD_OVERRIDER. The page also said only that the overrider is "marked inline", which does not tell a reader when to reach for it. Adds the reason, from the implementation comment above the macro and from test/dynamic_loading/shared_overrider.hpp: inline is what makes the repeated definition legal, and it is what lets initialize merge the repeated registrations instead of recording them as distinct overriders for one class and marking the call ambiguous.
…RIDER Points DECLARE at the rolex_2 example, the step in that progression that exists to show this split, in three blocks: roles.hpp declares the overrider without a body, employee.cpp supplies it, and salesman.cpp adds a more specialized overrider. The third is the contrast that makes the first two mean something -- an overrider defined in one place needs no split, so it uses plain BOOST_OPENMETHOD_OVERRIDE, and it reaches the declared one through BOOST_OPENMETHOD_OVERRIDER. All three regions were already tagged, and the example is compiled and run. The two macros are halves of one thing, so DEFINE links to DECLARE's Example section rather than repeating it, as BOOST_OPENMETHOD does with BOOST_OPENMETHOD_OVERRIDE. The lead-in says what the pair is for -- splitting an overrider across a header and an implementation file -- which is the part a reader cannot get from "declares an overrider" and "defines the body".
Shows the two ways to define the symbol, and what defining it buys: the call-time check in snippets/errors.cpp, where Bulldog is never registered and nothing is amiss until a call passes one. Verified both ways before writing it down -- with the symbol the call reports missing_class, without it the call goes through and returns normally. That check also turned up a bug in the snippet. It relied on default_registry carrying runtime_checks, which is only true because the snippets CMakeLists defines BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS in debug builds, so the last of its four examples would have failed in a release build. Compiling errors.cpp with -O2 and no define confirms it: one failure before, none after. The registry now names policies::runtime_checks explicitly. This completes the first table in ref_macros.adoc, the macros described there as sufficient for most uses.
The `report` region asserted the counts with BOOST_TEST. It now shows the branch a program would write: report on stderr that some methods are ambiguous or not implemented, point at BOOST_OPENMETHOD_TRACE, exit. The assertions stay, outside the tag. Also rewords the lead-in to the salesman.cpp block on BOOST_OPENMETHOD_DECLARE_OVERRIDER: what that overrider illustrates is that a specific overrider can be called explicitly from another, with no dynamic dispatch.
The four regions in snippets/errors.cpp rendered BOOST_CHECK_THROW(initialize<...>(), missing_class) on three reference pages. Boost.Test scaffolding is not what a reader needs, and the registry carried throw_error_handler, which implied you must select that policy to see the error at all. Each region is now the faulty registration and the one operation that reports it, with the description the library writes as a comment above it. The registry drops throw_error_handler and keeps the default handler. The harness moved out of the tags. It has to install an error handler because of two things the library does: the `output` policy writes to the C stderr stream, which a streambuf redirect cannot capture, and abort() follows as soon as the handler returns, so only throwing gets control back. The installed handler writes the same description to std::cerr -- same std::visit over the error variant as default_error_handler::default_handler -- and throws a type the caller catches, both outside the tagged regions. The assertions check the captured text, so the comments cannot drift from what is printed. The notes on the three pages now describe the default behavior, which is what the examples show.
Applies the treatment errors.cpp got to the rest, and finishes the job on errors.cpp itself. Assertions split two ways. Pointer and v-table identity -- the ~72 in virtual_ptr.cpp, plus the use_count ones -- stay as BOOST_TEST: stating which object and which v-table a pointer holds is what those examples are for. The 18 that checked what a method returned now print it, with the output as a trailing comment and the capture and BOOST_TEST outside the tag, the way macros.cpp already worked. Two shared helpers in capture.hpp replace what would have been six copies of the same redirect. The two error-handler examples in policies.cpp keep their try/catch -- there the fact that the error reaches your code is the example, not scaffolding -- and lose only BOOST_CHECK_THROW. initialize.cpp's exit(1) is neutralised by a #define outside the tag, as it is an example of what a program does, not something a test may do. errors.cpp is split into four translation units, one per mistake. It had carried a registry argument on every line so that one deliberate mistake could not poison another; separate translation units give that isolation for free, so the examples now use the default registry and no line mentions a registry at all. The marker-policy device and the reporting<N> alias go with it. The call example defines BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS itself rather than relying on a debug build, which is also what its page documents; verified at -O2 with no external define.
`{ /* ... */` on the brace line was clang-format's doing, and it renders
awkwardly. A line comment on its own line cannot be folded back up.
The example was on the `template<class Registry, typename Arg>` overload, so the plain `final_virtual_ptr(obj)` -- the one a reader reaches for -- had none, and the example looked as though it had been lost. It now sits on the default-registry overload, and the explicit-registry one links to it. That link needed the markup/a override extended. It rewrote `xref:ROOT:` on a nested page as a `link:`, because MrDocs sets relfileprefix there and Asciidoctor folds it into an xref target; a link from one reference page to another has exactly the same problem, and the same fix, minus the extra `../` since those targets are already relative to the reference module root.
`final_virtual_ptr` consults no dynamic type -- that is the whole point.
It takes the argument's static type as the object's class and uses
static_vptr for it, skipping the RTTI lookup. "Known dynamic type" says
close to the opposite.
"Known exact class" is also the phrasing the library already uses for the
same idea, in the three interop headers ("Since the exact class of the
object is known") and in static_rtti.
The two `virtual_ptr::final` members get it too. Their briefs were
"Construct a virtual_ptr from a reference to an object" and "... from a
smart pointer to an object", which describe an ordinary constructor and
leave out the precondition entirely.
The comment described what it does -- take the static type as the class, use static_vptr -- without saying why anyone would want that. Two reasons, now stated: it looks nothing up at runtime, where constructing from a reference or a pointer goes through the rtti policy for the dynamic type and the vptr policy for the v-table; and it is the only way to build a virtual_ptr under static_rtti, which has no dynamic type to consult and disables those constructors.
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.
MrDocs now extracts
#definedirectives as symbols (cppalliance/mrdocs#1192), so the macro reference no longer has to be written by hand.Changes
Doc comments on the macros. The content of the sixteen hand-written
BOOST_OPENMETHOD*.adocpages moves into//!comments inmacros.hpp,core.hppanddefault_registry.hpp— brief, description, notes, "Implementation Notes", and@paramfor every parameter. The pages are deleted;ref_macros.adocstays as the curated basic/advanced index, now pointing at the generated reference pages.Two macros needed restructuring to have a single documented definition:
BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKSis only ever tested, never defined by the library, so there was no directive to extract. It gets a documentation-only#defineunder__MRDOCS__, placed afterdefault_registryso documenting it cannot change what it documents.BOOST_OPENMETHOD_EXPORT_REGISTRYandBOOST_OPENMETHOD_INSTANTIATE_REGISTRYhad one definition per ABI. The per-platform bodies move intoBOOST_OPENMETHOD_DETAIL_*macros, so the public macros are defined — and documented — once instead of carrying duplicated doc comments.Macro parameters renamed
NAME/ARGS→ID/PARAMETERS. The generated synopsis prints the real parameter names (#define BOOST_OPENMETHOD(ID, PARAMETERS, ...)), and the prose has always called themIDandPARAMETERS.Links are real xrefs now.
{{MACRO}}placeholders in doc comments become@ref MACRO, which MrDocs resolves to anxref:; references to C++ symbols from macro pages use qualified names (@ref boost::openmethod::use_classes) since macros live in the global namespace. The guide pages'xref:BOOST_OPENMETHOD_X.adoc[becomexref:reference:BOOST_OPENMETHOD_X.adoc[(38 sites).build_antora.shloses two perl substitutions: the one that rewrote{{MACRO}}into a hand-built relative link, and the{{BASE_URL}}pass over the macro pages — MrDocs emits the "Declared in" GitHub link itself frombase-url.ref_headers.adocstill needs{{BASE_URL}}, so that one stays.doc/mrdocs.ymlgainsinclude-macros/exclude-macros.Testing
base_urlinref_headers.adoc, section levels, snippet tags). Every@refresolved — no literal@refleft in the generated adoc, and no_DETAIL_/GENSYM/GUIDEmacro leaked into the output.b2 -j12 toolset=gcc cxxstd=17intest/: 699 targets, all passed.-fsyntax-onlyover everytest/test_*.cppanddoc/modules/ROOT/examples/*.cpp: clean.clang-format -ion all edited headers.Notes
Ordered lists don't survive MrDocs doc comments — consecutive
1./2.lines collapse into a single paragraph — so the enumerated dispatch rules use@libullets instead of numbers.Reference now links back to the guide. MrDocs escapes prose punctuation but emits markdown-link targets verbatim, so
[Methods and Overriders](xref:ROOT:basics.adoc)in a doc comment comes out as a realxref:ROOT:basics.adoc[...]. Each macro page gets a See Also section pointing at the guide pages that cover it, using the nav labels as link text and only where the guide actually discusses the macro. The cross-reference between narrative docs and reference is now bidirectional.Such a link must be written on one line — MrDocs parses it after the comment is split into lines, and a wrapped link silently falls through as escaped literal text. That was already happening to the two
[CRTP mixin]links ininplace_vptr.hpp, fixed here too. Three dead@seeentries also became real references (@see indirect_vptr.rendered as escaped plain text; two@see The main template for documentation.had nothing to click).Only macro pages carry guide links. MrDocs writes
:relfileprefix: ../../into its nested reference pages — by design, its template says so — and Asciidoctor folds that into the xref target Antora resolves, soxref:ROOT:basics.adocarrives as../../ROOT:basics.adocand does not resolve. Macro pages sit at the reference module root, get no prefix, and work. Clearing the attribute fixes the nested pages but breaks ~1250 breadcrumb links, because theboost::openmethod::xrefs in the document title bypass Antora's resolver and genuinely need it. Reported upstream as relfileprefix on multipage pages blocks doc-comment links to non-reference pages cppalliance/mrdocs#1245; the C++ symbol pages can gain guide links once that is addressed.CI needs a MrDocs new enough to have macro support. An older one silently produces no macro pages, which breaks the
reference:xrefs. My local cache was a build from two days before #1192 merged and had to be cleared.🤖 Generated with Claude Code