rework trace

Author: jll63

doc/modules/ROOT/pages/BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS.adoc

@@ -0,0 +1,20 @@
+= xref:macros.adoc[Macro] BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS
+
+Enable runtime checks in method calls.
+
+== Synopsis
+
+May be defined by a program before including
+`<boost/openmethod/default_registry.hpp>`.
+
+== Description
+
+`BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS` enables runtime checks in method calls,
+for the methods in the
+link:reference/boost/openmethod/default_registry.html[`default_registry`]. These
+checks can find missing registrations for classes that are used in method calls,
+but not in method or overrider virtual parameters.
+
+Use with caution, as inconsistent use of this macro can cause ODR violations. If
+defined, it must be in all the translation units in the program that use
+`default_registry`, including those pulled from libraries.

doc/modules/ROOT/pages/macros.adoc

@@ -5,27 +5,29 @@
 [cols=2]
 |===
 | Name
-| Description
+| Description.
 | xref:BOOST_OPENMETHOD.adoc[BOOST_OPENMETHOD]
-| Declare a method
+| Declare a method.
 | xref:BOOST_OPENMETHOD_CLASSES.adoc[BOOST_OPENMETHOD_CLASSES]
-| registers classes
+| registers classes.
 | xref:BOOST_OPENMETHOD_DECLARE_OVERRIDER.adoc[BOOST_OPENMETHOD_DECLARE_OVERRIDER]
-| Declare a method overrider
-| xref:BOOST_OPENMETHOD_DEFAULT_REGISTRY.adoc[BOOST_OPENMETHOD_DEFAULT_REGISTRY]
-| Default registry
+| Declare a method overrider.
 | xref:BOOST_OPENMETHOD_DEFINE_OVERRIDER.adoc[BOOST_OPENMETHOD_DEFINE_OVERRIDER]
-| Define the body of a method overrider
+| Define the body of a method overrider.
 | xref:BOOST_OPENMETHOD_ID.adoc[BOOST_OPENMETHOD_ID]
-| Generate a method id
+| Generate a method id.
 | xref:BOOST_OPENMETHOD_INLINE_OVERRIDE.adoc[BOOST_OPENMETHOD_INLINE_OVERRIDE]
-| Add an overrider to a method as an inline function
+| Add an overrider to a method as an inline function.
 | xref:BOOST_OPENMETHOD_OVERRIDE.adoc[BOOST_OPENMETHOD_OVERRIDE]
-| Add an overrider to a method
+| Add an overrider to a method.
 | xref:BOOST_OPENMETHOD_OVERRIDER.adoc[BOOST_OPENMETHOD_OVERRIDER]
-| Return the class template specialization containing an overrider
+| Return the class template specialization containing an overrider.
 | xref:BOOST_OPENMETHOD_OVERRIDERS.adoc[BOOST_OPENMETHOD_OVERRIDERS]
-| Return the class template containing the overriders for all the methods with a given name
+| Return the class template containing the overriders for all the methods with a given name.
 | xref:BOOST_OPENMETHOD_REGISTER.adoc[BOOST_OPENMETHOD_REGISTER]
-| Create a registrar object
+| Create a registrar object.
+| xref:BOOST_OPENMETHOD_DEFAULT_REGISTRY.adoc[BOOST_OPENMETHOD_DEFAULT_REGISTRY]
+| Default registry.
+| xref:BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS.adoc[BOOST_OPENMETHOD_ENABLE_RUNTIME_CHECKS]
+| Enable runtime checks in method calls.
 |===

include/boost/openmethod/initialize.hpp

@@ -1547,21 +1547,61 @@ struct initialize_aux<
 //!
 //! If the first template argument is a registry, initialize it. Otherwise,
 //! initialize the default registry. Additional template arguments, if any, must
-//! be option types (@ref n2216 or @ref has_trace).
+//! be option types (@ref n2216 or @ref trace).
+//!
+//! The function returns an object of an unspecified type that contains a
+//! `report` member, itself an object of an unspecified type, that
+//! provides information about the initialization process. Its members are:
+//! @li `std::size_t cells`: The number of cells in all multi-method dispatch
+//! tables.
+//! @li `std::size_t not_implemented`: The number of multi-method dispatch tables that
+//! contain at least one not implemented entry.
+//! @li `std::size_t ambiguous`: The number of multi-method dispatch tables that contain at
+//! least one ambiguous entry.
 //!
 //! @note
 //! A translation unit that contains a call to `initialize` must include the
 //! `<boost/openmethod/initialize.hpp>` header.
 //!
+//! @tparam Class... An optional @registry type followed by zero or more option
+//! types.
+//!
+//! @return An object of an unspecified type.
+//!
 //! @par Errors
 //!
-//! @li @ref missing_class: A class used in a virtual parameter was
-//! not registered.
+//! @li @ref missing_class: A class used in a virtual parameter was not
+//! registered.
+//! @li The registry's policies may report additional errors.
+//!
+//! @par Example
+//!
+//! Initialize the default registry with tracing enabled, and exit
+//! with an error message if there were any possibility of a @reg bad_call
+//! error. User may run the program again with `BOOST_OPENMETHOD_TRACE=1` to
+//! troubleshoot.
+//!
+//! @code
+//! #include <iostream>
+//!
+//! #include <boost/openmethod.hpp>
+//! #include <boost/openmethod/initialize.hpp>
+//!
+//! int main() {
+//!     namespace bom = boost::openmethod;
+//!     auto report = bom::initialize<bom::trace>().report;
+//!
+//!     if (report.not_implemented != 0 || report.ambiguous != 0) {
+//!         std::cerr << "missing overriders or ambiguous methods\n";
+//!         return 1;
+//!     }
 //!
-//! @li Errors reported by the policies.
-template<class... T>
+//!     // ...
+//! }
+//! @endcode
+template<class... Class>
 inline auto initialize() {
-    return detail::initialize_aux<void, T...>::fn();
+    return detail::initialize_aux<void, Class...>::fn();
 }
 
 namespace detail {

include/boost/openmethod/options.hpp

@@ -27,21 +27,21 @@ struct n2216 : detail::option_base {};
 
 //! Enable `initialize` tracing.
 //!
-//! If `trace` is present, trace instructions are added to various parts of the
-//! initialization process (dispatch table construction, hash factors search,
-//! etc). These instructions are executed only if `trace::fn<Registry>::on` is
-//! set to `true`. The default value of `on` is `true` if environment variable
-//! `BOOST_OPENMETHOD_TRACE` is set to the string "1". At the moment, any other
-//! value disables tracing.
+//! If `trace` is present in @ref initialize\'s `Options`, tracing code is added
+//! to various parts of the initialization process (dispatch table construction,
+//! hash factors search, etc). The tracing code is executed only if
+//! @ref trace::on is set to `true`. The default value of `on` is `true` if
+//! environment variable `BOOST_OPENMETHOD_TRACE` is set to the string "1", and
+//! false otherwise.
 //!
-//! `trace` requires an `output` policy to be present. Trace is written to its
-//! output stream.
+//! `trace` requires the registry being initialized to have an @ref output
+//! policy.
 //!
-//! The exact format of the trace output is not specified, and may change at any
-//! time. The only guarantee is that it is detailed and comprehensive, and makes
-//! it possible to troubleshoot problems like missing class registrations,
-//! missing or ambiguous overriders, etc.
+//! The content of the trace is neither specified, nor stable across versions.
+//! It is comprehensive, and useful for troubleshooting missing class
+//! registrations, missing or ambiguous overriders, etc.
 struct trace : detail::option_base {
+    //! Enable trace.
     static bool on;
 };
 

include/boost/openmethod/registry.hpp

@@ -371,7 +371,9 @@ struct LightweightOutputStream {
 
 #endif
 
-//! Namespace containing the policy framework.
+//! Namespace for the policies.
+//!
+//! @see @ref registry for an explanation of policies.
 
 namespace policies {
 
@@ -754,18 +756,17 @@ struct initialize_aux;
 
 } // namespace detail
 
-//! A collection of methods, classes and policies.
+//! Methods, classes and policies.
 //!
 //! Methods exist in the context of a registry. Any class used as a method or
 //! overrider parameter, or in as a method call argument, must be registered
 //! with the same registry.
 //!
-//! Before calling a method, the @ref registry::initialize function must be
-//! called for its registry to set up the dispatch tables. This is typically
-//! done at the beginning of `main`.
+//! Before calling a method, its registry must be initialized with the @ref
+//! initialize function. This is typically done at the beginning of `main`.
 //!
 //! Multiple registries can co-exist in the same program. They must be
-//! initialized independently. Classes referenced by methods in different
+//! initialized individually. Classes referenced by methods in different
 //! registries must be registered with each registry.
 //!
 //! A registry also contains a set of @ref policies that control how certain
@@ -774,9 +775,10 @@ struct initialize_aux;
 //! interface with custom RTII systems (like LLVM's).
 //!
 //! Policies are implemented as Boost.MP11 quoted meta-functions. A policy class
-//! must contain a `fn<Registry>` template that provides a set of _static_
-//! members, specific to each policy category. Registries instantiate policies
-//! by passing themselves to the nested `fn` class templates.
+//! must contain a `fn<Registry>` template that provides a set of static
+//! members, specific to the responsibility of the policy. Registries
+//! instantiate policies by passing themselves to the nested `fn` class
+//! templates.
 //!
 //! There are two reason for this design.
 //!