doc: document macros with MrDocs

[jll63]

MrDocs now extracts #define directives 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*.adoc pages moves into //! comments in macros.hpp, core.hpp and default_registry.hpp — brief, description, notes, "Implementation Notes", and @param for every parameter. The pages are deleted; 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. It gets a documentation-only #define under __MRDOCS__, placed 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. The per-platform bodies move into BOOST_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 them ID and PARAMETERS.

• Links are real xrefs now. {{MACRO}} placeholders in doc comments become @ref MACRO, which MrDocs resolves to an xref:; 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[ become xref:reference:BOOST_OPENMETHOD_X.adoc[ (38 sites).

• build_antora.sh loses 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 from base-url. ref_headers.adoc still needs {{BASE_URL}}, so that one stays.

• doc/mrdocs.yml gains include-macros / exclude-macros.

Testing

• Full doc build: all sixteen macro pages generated, 0 asciidoctor errors; the remaining warnings are all pre-existing (base_url in ref_headers.adoc, section levels, snippet tags). Every @ref resolved — no literal @ref left in the generated adoc, and no _DETAIL_ / GENSYM / GUIDE macro leaked into the output.
• b2 -j12 toolset=gcc cxxstd=17 in test/: 699 targets, all passed.
• -fsyntax-only over every test/test_*.cpp and doc/modules/ROOT/examples/*.cpp: clean.
• clang-format -i on 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 @li bullets instead of numbers.
• The macro pages point at the Shared Libraries guide in plain text rather than as a link: an Antora xref: inside a doc comment gets entity-escaped by MrDocs. The guide still links to the macros, so the cross-reference works in one direction.
• 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

[jll63]

Superseded by boostorg#83 — opened against the canonical repository instead.