jll63 · Oct 6, 2026
@@ -421,8 +421,8 @@ literal `href="#reference:<NAME>.adoc"`.
 
 ### Doc-comment markup traps
 
-MrDocs parses `//!` comments as Markdown plus Doxygen commands, then emits AsciiDoc. Four shapes
-mis-render silently; all four were found by rendering, none by reading the source:
+MrDocs parses `//!` comments as Markdown plus Doxygen commands, then emits AsciiDoc. Five shapes
+mis-render silently; all five were found by rendering, none by reading the source:
 
 - **A line starting with `- ` becomes a list item.** House style uses ` - ` as an em-dash, which is
   fine mid-line but starts a stray bullet at the head of one. Rewrap so the dash never begins a
@@ -435,6 +435,15 @@ mis-render silently; all four were found by rendering, none by reading the sourc
 - **`@attention` is dropped silently**, paragraph and all: no admonition, no text, no warning.
   MrDocs knows `@note` and `@warning`, which render as NOTE and WARNING blocks wherever they sit in
   the description - the first paragraph after the brief included. Use one of those.
+- **A code span followed by a letter keeps its backticks**: `` `type_id`s `` renders as a literal
+  `` `type_id`s ``, and the next code span in the paragraph loses its formatting. MrDocs passes the
+  span to AsciiDoc as is, and a constrained span cannot end inside a word. Reword - "type ids",
+  "`virtual_ptr` objects". A possessive (`` `obj`'s ``) is safe here, unlike in an `.adoc` page:
+  MrDocs writes the apostrophe as `&apos;`. Before building:
+
+  ```bash
+  grep -rnE '//!.*`[^` ]+`[A-Za-z]' include/    # must return nothing
+  ```
 
 An `xref:reference:<name>.adoc` path works only for macros, which MrDocs puts at the top level.
 A namespace-scoped symbol lives under `reference/boost/openmethod/`, so link it with

@@ -166,9 +166,9 @@ struct registry_affinity_aux;
 //! the derived-to-base pointer conversion makes the base's overload viable. An
 //! overload on the derived class itself is a better match, and wins.
 //!
-//! A class can also declare its affinity with a member typedef, `using
-//! boost_openmethod_registry = Registry;`. It is looked up first, and it is
-//! inherited like any member - a derived class's typedef hides the base's.
+//! A class can also declare its affinity with a member typedef,
+//! `using boost_openmethod_registry = Registry;`. It is looked up first, and it
+//! is inherited like any member - a derived class's typedef hides the base's.
 //! Being visible from the point it is declared, it is the spelling for a class
 //! that mentions `virtual_ptr` of itself in its own body - which a class that
 //! declares no affinity may do freely.
@@ -931,7 +931,7 @@ BOOST_OPENMETHOD_OPEN_NAMESPACE_DETAIL_UNLESS_MRDOCS
 //! Evaluates to `true` if `Class` is a polymorphic type, according to the
 //! `rtti` policy of `Registry`.
 //!
-//! If Registry's `rtti` policy is std_rtti`, this is the same as
+//! If the `rtti` policy of `Registry` is `std_rtti`, this is the same as
 //! `std::is_polymorphic`. However, other `rtti` policies may have a different
 //! view of what is polymorphic.
 //!
@@ -1340,7 +1340,7 @@ class virtual_ptr {
 
     //! Construct a `virtual_ptr` from another `virtual_ptr`
     //!
-    //! Copy the object and v-table pointers from `other` to `this.
+    //! Copy the object and v-table pointers from `other` to `this`.
     //!
     //! `Other` is _not_ required to be a pointer to a polymorphic class.
     //!
@@ -1450,7 +1450,7 @@ class virtual_ptr {
 
     //! Assign a `virtual_ptr` from another `virtual_ptr`
     //!
-    //! Copy the object and v-table pointers from `other` to `this.
+    //! Copy the object and v-table pointers from `other` to `this`.
     //!
     //! `Other` is _not_ required to be a pointer to a polymorphic class.
     //!
@@ -2095,7 +2095,7 @@ virtual_ptr(Class&& obj) -> virtual_ptr<Class, registry_affinity<Class>>;
 // template<class Registry, class Class>
 // virtual_ptr<Registry>(Class&) -> virtual_ptr<Class, Registry>;
 
-//! Compare two `virtual_ptr`s for equality.
+//! Compare two `virtual_ptr` objects for equality.
 //!
 //! Compare the underlying object pointers for equality. The v-table pointers
 //! are not compared.
@@ -2105,16 +2105,16 @@ virtual_ptr(Class&& obj) -> virtual_ptr<Class, registry_affinity<Class>>;
 //! @tparam Registry A @ref registry.
 //! @param left A reference to a `virtual_ptr`.
 //! @param right A reference to a `virtual_ptr`.
-//! @return `true` if both `virtual_ptr`s point to the same object or both
-//! are `nullptr`, `false` otherwise.
+//! @return `true` if both `virtual_ptr` objects point to the same object, or
+//! both are `nullptr`, `false` otherwise.
 template<class Left, class Right, class Registry>
 auto operator==(
     const virtual_ptr<Left, Registry>& left,
     const virtual_ptr<Right, Registry>& right) -> bool {
     return left.pointer() == right.pointer();
 }
 
-//! Compare two `virtual_ptr`s for inequality.
+//! Compare two `virtual_ptr` objects for inequality.
 //!
 //! Compare the underlying object pointers for inequality. The v-table pointers
 //! are not compared.
@@ -2123,8 +2123,8 @@ auto operator==(
 //! @tparam Registry A @ref registry.
 //! @param left A reference to a `virtual_ptr`.
 //! @param right A reference to a `virtual_ptr`.
-//! @return `true` if both `virtual_ptr`s point to different objects, or one
-//! is `nullptr` and the other is not, `false` otherwise.
+//! @return `true` if both `virtual_ptr` objects point to different objects,
+//! or one is `nullptr` and the other is not, `false` otherwise.
 template<class Left, class Right, class Registry>
 auto operator!=(
     const virtual_ptr<Left, Registry>& left,

@@ -96,8 +96,8 @@ struct virtual_traits<const boost::intrusive_ptr<Class>&, Registry> {
     //! Cast a `boost::intrusive_ptr` to a `boost::intrusive_ptr` to a derived
     //! class, using a static cast if possible, and a dynamic cast otherwise.
     //!
-    //! @tparam OverriderType The type required by the overrider (a `const
-    //! boost::intrusive_ptr&`).
+    //! @tparam OverriderType The type required by the overrider (a
+    //! `const boost::intrusive_ptr&`).
     //! @param obj The method's argument..
     //! @return A `boost::intrusive_ptr` _value_.
     template<class OverriderType>

@@ -88,8 +88,8 @@ inline boost::mp11::mp_apply<
 //! `Any`: naming a type as the parameter of an overrider - or storing a
 //! value in a `virtual_any` - registers it in `Registry`.
 //!
-//! Methods take `virtual_any` parameters by reference: `const
-//! virtual_any&`, `virtual_any&` or `virtual_any&&`. Overriders receive
+//! Methods take `virtual_any` parameters by reference:
+//! `const virtual_any&`, `virtual_any&` or `virtual_any&&`. Overriders receive
 //! the *contained* type, by a reference of a compatible category - or the
 //! `virtual_any` itself, unchanged, for a catch-all overrider.
 //!

@@ -58,9 +58,9 @@ namespace boost::openmethod::policies {
 //! sparse set, this one spends `8 * n * 100 / LoadPercent` bytes of v-table
 //! vector plus `4 * n / Lambda` bytes of pilots **whatever the addresses are**,
 //! and its search time depends only on how many type ids there are, not where
-//! they sit. That makes it the policy to reach for in a program that `dlopen`s
-//! modules registering classes of their own, where type ids from different
-//! modules are far apart and in unrelated ranges.
+//! they sit. That makes it the policy to reach for in a program that uses
+//! `dlopen` to load modules registering classes of their own, where type ids
+//! from different modules are far apart and in unrelated ranges.
 //!
 //! The price is on the dispatch path: the pilot must be loaded before the index
 //! can be formed, so the v-table lookup becomes two dependent loads instead of

@@ -84,7 +84,7 @@ struct std_rtti : rtti {
         //! C++ does *not* guarantee that there is a single instance of
         //! `std::type_info` per type: a class used by several modules of a
         //! program typically has one per module. `type_index` maps a `type_id`
-        //! to a key that compares equal for all the `type_id`s of one class,
+        //! to a key that compares equal for all the type ids of one class,
         //! which is what @ref initialize uses to group the registrations coming
         //! from different modules.
         //!

@@ -24,9 +24,9 @@ namespace boost::openmethod {
 
 namespace policies {
 
-//! Stores v-table pointers in a map keyed by `type_id`s.
+//! Stores v-table pointers in a map keyed by `type_id`.
 //!
-//! `vptr_map` stores v-table pointers in a map keyed by `type_id`s.
+//! `vptr_map` stores v-table pointers in a map keyed by `type_id`.
 //!
 //! If the registry contains the @ref indirect_vptr policy, `vptr_map` stores
 //! pointers to pointers to v-tables.

@@ -28,8 +28,8 @@ namespace policies {
 //! Stores v-table pointers in a vector.
 //!
 //! `vptr_vector` stores v-table pointers in a global vector. If `Registry`
-//! contains a @ref type_hash policy, it is used to convert `type_id`s to
-//! indices. Otherwise, `type_id`s are used directly as indices.
+//! contains a @ref type_hash policy, it is used to convert type ids to
+//! indices. Otherwise, type ids are used directly as indices.
 //!
 //! If the registry contains the @ref indirect_vptr policy, stores pointers to
 //! pointers to v-tables in the vector.
@@ -45,7 +45,7 @@ struct vptr_vector : vptr {
     //! Keeps track of v-table pointers using a `std::vector`.
     //!
     //! If `Registry` contains a @ref type_hash policy, it is used to convert
-    //! `type_id`s to indices; otherwise, `type_id`s are used as indices.
+    //! type ids to indices; otherwise, type ids are used as indices.
     //!
     //! If `Registry` contains the @ref indirect_vptr policy, stores pointers to
     //! pointers to v-tables in the map.