From ed30c40499516d3d02347ace83d03edd009c8404 Mon Sep 17 00:00:00 2001 From: Jean-Louis Leroy Date: Tue, 6 Oct 2026 19:08:05 -0400 Subject: [PATCH] doc: fix code spans that render with literal backticks A code span followed by a letter - `type_id`s, `virtual_ptr`s, `dlopen`s - is passed by MrDocs to AsciiDoc as is, where a constrained span cannot end inside a word: the backticks come through literally, and the next code span in the paragraph loses its formatting (`nullptr` in operator== and operator!=). Reworded: "type ids", "`virtual_ptr` objects", "uses `dlopen` to load". The same scan of the rendered reference found three other broken spans, fixed too: a missing opening backtick (IsPolymorphic), two missing closing ones (virtual_ptr's converting constructor and assignment), and three spans split across two `//!` lines (boost_openmethod_registry, virtual_any, the intrusive_ptr virtual_traits). CLAUDE.md: document the plural trap among the doc-comment markup traps, with a grep. A possessive is safe in a doc comment: MrDocs writes the apostrophe as '. After the change, no rendered page has a backtick outside a code block. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 13 ++++++++-- include/boost/openmethod/core.hpp | 24 +++++++++---------- .../interop/boost_intrusive_ptr.hpp | 4 ++-- .../boost/openmethod/interop/virtual_any.hpp | 4 ++-- .../policies/minimal_perfect_hash.hpp | 6 ++--- .../boost/openmethod/policies/std_rtti.hpp | 2 +- .../boost/openmethod/policies/vptr_map.hpp | 4 ++-- .../boost/openmethod/policies/vptr_vector.hpp | 6 ++--- 8 files changed, 36 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ea80ae0c..acefc627 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -421,8 +421,8 @@ literal `href="#reference:.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 `'`. Before building: + + ```bash + grep -rnE '//!.*`[^` ]+`[A-Za-z]' include/ # must return nothing + ``` An `xref:reference:.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 diff --git a/include/boost/openmethod/core.hpp b/include/boost/openmethod/core.hpp index e363db1a..f3a7c474 100644 --- a/include/boost/openmethod/core.hpp +++ b/include/boost/openmethod/core.hpp @@ -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>; // template // virtual_ptr(Class&) -> virtual_ptr; -//! 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,8 +2105,8 @@ virtual_ptr(Class&& obj) -> virtual_ptr>; //! @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 auto operator==( const virtual_ptr& left, @@ -2114,7 +2114,7 @@ auto operator==( 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 auto operator!=( const virtual_ptr& left, diff --git a/include/boost/openmethod/interop/boost_intrusive_ptr.hpp b/include/boost/openmethod/interop/boost_intrusive_ptr.hpp index 16dd5b91..039a92cd 100644 --- a/include/boost/openmethod/interop/boost_intrusive_ptr.hpp +++ b/include/boost/openmethod/interop/boost_intrusive_ptr.hpp @@ -96,8 +96,8 @@ struct virtual_traits&, 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 diff --git a/include/boost/openmethod/interop/virtual_any.hpp b/include/boost/openmethod/interop/virtual_any.hpp index 763661be..c0179f37 100644 --- a/include/boost/openmethod/interop/virtual_any.hpp +++ b/include/boost/openmethod/interop/virtual_any.hpp @@ -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. //! diff --git a/include/boost/openmethod/policies/minimal_perfect_hash.hpp b/include/boost/openmethod/policies/minimal_perfect_hash.hpp index df24d088..db64c578 100644 --- a/include/boost/openmethod/policies/minimal_perfect_hash.hpp +++ b/include/boost/openmethod/policies/minimal_perfect_hash.hpp @@ -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 diff --git a/include/boost/openmethod/policies/std_rtti.hpp b/include/boost/openmethod/policies/std_rtti.hpp index 09ca684c..8acd6d89 100644 --- a/include/boost/openmethod/policies/std_rtti.hpp +++ b/include/boost/openmethod/policies/std_rtti.hpp @@ -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. //! diff --git a/include/boost/openmethod/policies/vptr_map.hpp b/include/boost/openmethod/policies/vptr_map.hpp index 7685cb26..a05db22d 100644 --- a/include/boost/openmethod/policies/vptr_map.hpp +++ b/include/boost/openmethod/policies/vptr_map.hpp @@ -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. diff --git a/include/boost/openmethod/policies/vptr_vector.hpp b/include/boost/openmethod/policies/vptr_vector.hpp index c6bfe6fd..107938f7 100644 --- a/include/boost/openmethod/policies/vptr_vector.hpp +++ b/include/boost/openmethod/policies/vptr_vector.hpp @@ -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.