registry.hpp -> preamble.hpp

Author: jll63

doc/modules/ROOT/pages/BOOST_OPENMETHOD_DEFAULT_REGISTRY.adoc

@@ -17,15 +17,20 @@ The name of the default registry.
 `BOOST_OPENMETHOD_DEFAULT_REGISTRY` is the default value for the `Registry`
 template parameter of `method`, `use_classes`, and other constructs defined in
 `<boost/openmethod/core.hpp>`. If it is not defined,
-link:reference/boost/openmethod/default_registry.html[`default_registry`] is used.
+link:reference/boost/openmethod/default_registry.html[`default_registry`] is
+used.
 
 `BOOST_OPENMETHOD_DEFAULT_REGISTRY` can be defined by a program to change the
-default REGISTRY globally. Once `<boost/openmethod/core.hpp>` has been included,
-redefining the symbol has no effect. To override the default REGISTRY, proceed as
-follows:
+default registry globally. Once `<boost/openmethod/core.hpp>` has been included,
+redefining the symbol has no effect. To override the default registry, proceed
+as follows:
+
+1. Include `<boost/openmethod/preamble.hpp>`, and
+`<boost/openmethod/default_registry.hpp>` or any of the
+`<boost/openmethod/policies/*.hpp>` as needed.
+
+2. Set `BOOST_OPENMETHOD_DEFAULT_REGISTRY`.
 
-1. Include headers under `boost/openmethod/policies/` as needed.
-2. Create a REGISTRY class, and set `BOOST_OPENMETHOD_DEFAULT_REGISTRY`.
 3. Include `<boost/openmethod/core.hpp>`.
 
 Use this feature with caution, as it can easily lead to ODR violations if

include/boost/openmethod/core.hpp

@@ -537,23 +537,25 @@ inline vptr_type null_vptr = nullptr;
 
 } // namespace detail
 
-//! Create a `virtual_ptr` for an object of an exact known type
-//!
-//! `final_virtual_ptr` creates a `virtual_ptr` to an object, setting its
-//! v-table pointer according to the declared type of its argument. It assumes
-//! that the static and dynamic types are the same. The v-table pointer is
-//! initialized from the `Policy::static_vptr` for the class, which needs
-//! not be polymorphic.
-//!
-//! @par Errors If the registry has runtime checks enabled, and the argument is
-//! a class type that is polymorphic according to the registry's `rtti` policy,
-//! a check is performed to verify that the static and dynamic types are indeed
-//! the same. If they are not, and if the registry contains an @ref
-//! error_handler policy, its
-//! @ref error function is called with a @ref final_error value, then the
-//! program is terminated with @ref abort.
-//!
-//! @tparam Registry The registry in which the class is registered.
+//! Creates a `virtual_ptr` for an object of a known dynamic type.
+//!
+//! Creates a @ref virtual_ptr to an object, setting its v-table pointer
+//! according to the declared type of its argument. Assumes that the static and
+//! dynamic types are the same. Sets the v-table pointer to the
+//! @ref registry::static_vptr for the class.
+//!
+//! `Class` is _not_ required to be polymorphic.
+//!
+//! If runtime checks are enabled, and the argument is polymorphic, checks if
+//! the static and dynamic types are the same. If not, calls the error handler
+//! with a @ref final_error value, then terminates the program with @ref abort.
+//!
+//! @par Errors
+//!
+//! @li @ref final_error The static and dynamic types of the object are
+//! different.
+//!
+//! @tparam Registry A @ref registry.
 //! @tparam Arg The type of the argument.
 //! @param obj A reference to an object.
 //! @return A `virtual_ptr<Class, Registry>` pointing to `obj`.
@@ -590,6 +592,12 @@ inline auto final_virtual_ptr(Arg&& obj) {
             Registry::template static_vptr<Class>));
 }
 
+//! Create a `virtual_ptr` for an object of a known dynamic type.
+//!
+//! This is an overload of `final_virtual_ptr` that uses the default
+//! registry as the `Registry` template parameter.
+//!
+//! @see @ref final_virtual_ptr
 template<class Arg>
 inline auto final_virtual_ptr(Arg&& obj) {
     return final_virtual_ptr<BOOST_OPENMETHOD_DEFAULT_REGISTRY, Arg>(
@@ -611,16 +619,14 @@ inline auto final_virtual_ptr(Arg&& obj) {
 //! "plain" `virtual_ptr` can be constructed from a smart `virtual_ptr`, but not
 //! the other way around.
 //!
-//! TODO: link out from mrdocs to macro documentation
-//! The default value for `Registry` can be customized by defining the <a href="openmethod/BOOST_OPENMETHOD_DEFAULT_REGISTRY.html">BOOST_OPENMETHOD_DEFAULT_REGISTRY</a>
+//! The default value for `Registry` can be customized by defining the
+//! [BOOST_OPENMETHOD_DEFAULT_REGISTRY](../BOOST_OPENMETHOD_DEFAULT_REGISTRY.html)
 //! preprocessor symbol.
 //!
 //! The default value for `Registry` can be customized by defining the
 //! xref:BOOST_OPENMETHOD_DEFAULT_REGISTRY.adoc[`BOOST_OPENMETHOD_DEFAULT_REGISTRY`]
 //! preprocessor symbol.
 //!
-//! @par Examples
-//!
 //! @par Requirements
 //!
 //! @li @ref virtual_traits must be specialized for `Class&`.