From b2e72934f8c0e44f30537ce4d7f55b2200d462c0 Mon Sep 17 00:00:00 2001 From: Jean-Louis Leroy Date: Fri, 11 Sep 2026 00:10:44 -0400 Subject: [PATCH] doc: stop @ref from swallowing the colon after it A colon is legal in a qualified C++ name, so MrDocs takes one that immediately follows an @ref as part of the target. The colon then disappears from the output. Thirteen doc comments did this, and every one of them rendered wrong: @li @ref policies::std_rtti: Use standard RTTI. became "`policies::std_rtti` Use standard RTTI." - the separator gone, two sentences run together. Nothing in the build catches it, because the reference still resolves; only the punctuation is lost. A period is not a valid identifier character, so it survives, and every one of these descriptions already began with a capital - so nine of the thirteen are a one-character change. Three more are a colon that introduces a code block, which has to stay a colon, so it now attaches to a word instead of to the reference ("..., as follows:"). The last, in boost_type_erasure.hpp, had a colon introducing an explanation mid-sentence, and becomes a full stop. Three other spellings were tried and rejected, by rendering them: - `{empty}` between the reference and the colon, which is how an .adoc page would do it, comes out as a literal "{empty}" - MrDocs escapes the braces - and the colon is still eaten. - a space before the colon does work, but leaves " :" in the prose. - the house ` - ` em-dash is the worst of the three: at the start of the text that follows a reference it becomes a *nested list item*, so each entry rendered as a bullet with a sub-bullet under it and the description one level too deep. Verified by generating the reference and checking all thirteen: each separator is present, each link still resolves, and the policy list in default_registry has no sub-bullets. --- include/boost/openmethod/core.hpp | 4 ++-- include/boost/openmethod/default_registry.hpp | 12 ++++++------ include/boost/openmethod/initialize.hpp | 2 +- .../boost/openmethod/interop/boost_type_erasure.hpp | 4 ++-- include/boost/openmethod/macros.hpp | 4 ++-- include/boost/openmethod/preamble.hpp | 2 +- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/include/boost/openmethod/core.hpp b/include/boost/openmethod/core.hpp index 39b2a530..9fd0d476 100644 --- a/include/boost/openmethod/core.hpp +++ b/include/boost/openmethod/core.hpp @@ -2128,8 +2128,8 @@ class method : //! If `Registry` contains an @ref error_handler policy, call its `error` //! function with an object of one of the following types: //! - //! @li @ref no_overrider: No overrider is applicable. - //! @li @ref ambiguous_call: More than one overrider is applicable, and + //! @li @ref no_overrider. No overrider is applicable. + //! @li @ref ambiguous_call. More than one overrider is applicable, and //! none is more specialized than all the others. //! auto operator()(typename BOOST_OPENMETHOD_UNLESS_MRDOCS(detail::) diff --git a/include/boost/openmethod/default_registry.hpp b/include/boost/openmethod/default_registry.hpp index 0c991fcc..c6219ab8 100644 --- a/include/boost/openmethod/default_registry.hpp +++ b/include/boost/openmethod/default_registry.hpp @@ -20,12 +20,12 @@ namespace boost::openmethod { //! `default_registry` is a predefined @ref registry, and the default value of //! @ref BOOST_OPENMETHOD_DEFAULT_REGISTRY. //! It contains the following policies: -//! @li @ref policies::std_rtti: Use standard RTTI. -//! @li @ref policies::fast_perfect_hash: Use a fast perfect hash function to +//! @li @ref policies::std_rtti. Use standard RTTI. +//! @li @ref policies::fast_perfect_hash. Use a fast perfect hash function to //! map type ids to indices. -//! @li @ref policies::vptr_vector: Store v-table pointers in a @c std::vector. -//! @li @ref policies::default_error_handler: Write short diagnostic messages. -//! @li @ref policies::stderr_output: Write messages to @c stderr. +//! @li @ref policies::vptr_vector. Store v-table pointers in a @c std::vector. +//! @li @ref policies::default_error_handler. Write short diagnostic messages. +//! @li @ref policies::stderr_output. Write messages to @c stderr. //! //! If @ref BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS //! is defined, `default_registry` also includes the @ref runtime_checks policy. @@ -38,7 +38,7 @@ namespace boost::openmethod { //! For a program and its shared libraries to contribute to the same //! `default_registry`, its state must be shared across the modules, with //! @ref BOOST_OPENMETHOD_IMPORT_REGISTRY, @ref BOOST_OPENMETHOD_EXPORT_REGISTRY -//! and @ref BOOST_OPENMETHOD_INSTANTIATE_REGISTRY: +//! and @ref BOOST_OPENMETHOD_INSTANTIATE_REGISTRY, as follows: //! @code //! // header, every translation unit of a client module: //! BOOST_OPENMETHOD_IMPORT_REGISTRY(boost::openmethod::default_registry); diff --git a/include/boost/openmethod/initialize.hpp b/include/boost/openmethod/initialize.hpp index 50d4ce56..7f4c4e8c 100644 --- a/include/boost/openmethod/initialize.hpp +++ b/include/boost/openmethod/initialize.hpp @@ -2211,7 +2211,7 @@ void registry::compiler::print_slots() { //! //! @par Errors //! -//! @li @ref missing_class: A class used in a virtual parameter was not +//! @li @ref missing_class. A class used in a virtual parameter was not //! registered. //! @li The registry's policies may report additional errors. //! diff --git a/include/boost/openmethod/interop/boost_type_erasure.hpp b/include/boost/openmethod/interop/boost_type_erasure.hpp index de09075d..fea69760 100644 --- a/include/boost/openmethod/interop/boost_type_erasure.hpp +++ b/include/boost/openmethod/interop/boost_type_erasure.hpp @@ -558,8 +558,8 @@ struct virtual_traits, Registry> { //! `boost::type_erasure::bad_function_call`. //! //! An `any` that carries this concept cannot be wrapped in a -//! @ref virtual_any: the hook returns the v-table pointer by value, and -//! an indirect registry cannot store that. Wrapping one is rejected at +//! @ref virtual_any. The hook returns the v-table pointer by value, and an +//! indirect registry cannot store that. Wrapping one is rejected at //! compile time. //! //! Both give constant-time access to the v-table pointer, but not at the diff --git a/include/boost/openmethod/macros.hpp b/include/boost/openmethod/macros.hpp index cf536e9d..fa26572a 100644 --- a/include/boost/openmethod/macros.hpp +++ b/include/boost/openmethod/macros.hpp @@ -289,7 +289,7 @@ inline constexpr bool method_not_found = false; //! include:../examples/rolex/2/roles.hpp#content //! //! The implementation file supplies the body with -//! @ref BOOST_OPENMETHOD_DEFINE_OVERRIDER: +//! @ref BOOST_OPENMETHOD_DEFINE_OVERRIDER, as follows: //! //! include:../examples/rolex/2/employee.cpp#content //! @@ -514,7 +514,7 @@ inline constexpr bool method_not_found = false; //! A translation unit that includes the header adds a more specialized //! overrider of its own. That one is defined once, so it uses //! @ref BOOST_OPENMETHOD_OVERRIDE; it reaches the header's overrider through -//! @ref BOOST_OPENMETHOD_OVERRIDER: +//! @ref BOOST_OPENMETHOD_OVERRIDER, as follows: //! //! include:../examples/rolex/3/salesman.cpp#content //! diff --git a/include/boost/openmethod/preamble.hpp b/include/boost/openmethod/preamble.hpp index 17943524..0a576d3d 100644 --- a/include/boost/openmethod/preamble.hpp +++ b/include/boost/openmethod/preamble.hpp @@ -1299,7 +1299,7 @@ class registry : public detail::registry_base { //! //! @par Errors //! - //! @li @ref not_initialized: The registry is not initialized. + //! @li @ref not_initialized. The registry is not initialized. static void require_initialized(); template