doc: forward-declare the registry instead of including preamble.hpp

[jll63]

Closes #90.

Overriding BOOST_OPENMETHOD_DEFAULT_REGISTRY forced users to learn the header layering: include a "pre-core" header (preamble.hpp or default_registry.hpp), define the registry, #define the macro, then include <boost/openmethod.hpp>. ref_headers.adoc codified that as a "Pre-Core Headers" section, and custom_rtti.adoc told the reader not to include <boost/openmethod.hpp> yet.

None of it is necessary. Every use of the macro in the headers is a name-only context — a default template argument, an alias, a deduction guide, or a member typedef inside a template — so the registry can be forward-declared before the include and defined after it:

struct my_registry;
#define BOOST_OPENMETHOD_DEFAULT_REGISTRY my_registry

#include <boost/openmethod.hpp>
#include <boost/openmethod/policies/vptr_map.hpp>   // extra policies, any order

struct my_registry
    : boost::openmethod::default_registry::with<
          boost::openmethod::policies::vptr_map<>> {};

core.hpp includes default_registry.hpp before it tests the macro, so by the time the definition is reached registry, default_registry, indirect_registry and the five stock policies are all complete. A registry the library provides needs no declaration at all — #define plus the include is the whole recipe. preamble.hpp and default_registry.hpp now appear nowhere outside include/.

Rules, all documented

• The registry must be complete before the first construct that instantiates it (a BOOST_OPENMETHOD* macro, use_classes, method, virtual_ptr, inplace_vptr_base, initialize(), or the registry-sharing macros). Violating this is a hard error, never silent.
• It must name a class, declared with the same class-key as the definition. A mismatch is MSVC C4099, an error under /W4 /WX.
• Qualify the name if it could also be found in namespace boost::openmethod. #define BOOST_OPENMETHOD_DEFAULT_REGISTRY registry resolves to boost::openmethod::registry and fails with missing template arguments; ::registry works.

What changed

• Headers — rewrote the BOOST_OPENMETHOD_DEFAULT_REGISTRY doc comment with both recipe shapes; fixed four other "before including core.hpp" comments.
• Tests — the 17 that override the default, plus test_policies.cpp. test_capture_errors.hpp now includes <boost/openmethod.hpp>; test_core.cpp drops a redundant preamble.hpp; dynamic_loading/registry.hpp loses its whole #ifndef fallback, which existed only because the alias preceded the include.
• Examples — the two custom_rtti step-by-step examples get a tag::setup[] region so tag::policy[] no longer opens with an include.
• Pages — ref_headers.adoc renames "Pre-Core Headers" to "Policy Headers" and demotes preamble.hpp/default_registry.hpp to "Headers Included by Other Headers". registries_and_policies.adoc becomes the canonical home of the recipe, and its reference to <boost/openmethod/registry.hpp> — a file that does not exist — is fixed. shared_libraries.adoc's my_registry.hpp listing gains the #define and include it was missing; as written it never actually overrode the default.

Drive-by cleanups

Removed doc/modules/ROOT/examples/deferred_custom_rtti.cpp: an orphan no page included, whose virtual-inheritance and dynamic_cast_ref coverage test_custom_rtti_virtual_base.cpp already provides. Also dropped three stray end:: tags with no opener and the dead Quickbook markers in examples/static_rtti.cpp.

Verification

• CMake + clang, Debug: 153/153 pass.
• CMake + gcc, Release, -Werror: 149/149 pass.
• b2: 334 targets clean, including both dynamic_loading variants (one supplies the macro on the command line) and both implicit_shared_libraries variants.
• MSVC 19.51 under /W4 /WX: the three declspec paths in implicit_shared_libraries/custom_registry and the migrated tests compile clean. No C4099 — every declaration and definition uses struct.
• Antora render: 17 warnings before, 17 after — no new markup issues. Delimiter parity even on every page, backtick-apostrophe grep clean, no leaked markup in the rendered HTML.

Note for anyone with an existing build tree: the glob in examples/CMakeLists.txt has no CONFIGURE_DEPENDS, so a manual cmake re-run is needed to drop the deleted example's target.

🤖 Generated with Claude Code

[cppalliance-bot]

An automated preview of the documentation is available at https://93.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-24 00:51:12 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.94%. Comparing base (725d5fd) to head (9e0e299).
⚠️ Report is 3 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop      #93      +/-   ##
===========================================
- Coverage    94.97%   92.94%   -2.04%     
===========================================
  Files           99       22      -77     
  Lines         4322     1615    -2707     
  Branches      2138      500    -1638     
===========================================
- Hits          4105     1501    -2604     
+ Misses         160       66      -94     
+ Partials        57       48       -9     

Files with missing lines	Coverage Δ
include/boost/openmethod/core.hpp	93.06% <ø> (ø)
include/boost/openmethod/default_registry.hpp	100.00% <ø> (ø)
include/boost/openmethod/policies/static_rtti.hpp	100.00% <ø> (ø)

... and 78 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 25d13ee...9e0e299. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.