registry.hpp -> preamble.hpp

Author: jll63

doc/modules/ROOT/examples/custom_rtti.cpp

@@ -31,7 +31,7 @@ struct Dog : Animal {
     static constexpr unsigned static_type = 3;
 };
 
-#include <boost/openmethod/registry.hpp>
+#include <boost/openmethod/preamble.hpp>
 #include <boost/openmethod/policies/vptr_vector.hpp>
 
 // tag::policy[]

doc/modules/ROOT/examples/deferred_custom_rtti.cpp

@@ -76,7 +76,7 @@ struct Dog : virtual Animal {
     static custom_type_info type_info;
 };
 
-#include <boost/openmethod/registry.hpp>
+#include <boost/openmethod/preamble.hpp>
 #include <boost/openmethod/policies/vptr_vector.hpp>
 
 namespace bom = boost::openmethod;

doc/modules/ROOT/pages/headers.adoc

@@ -2,45 +2,140 @@
 = xref:headers.adoc[Headers]
 :toc:
 
-### boost/openmethod.hpp
+{empty}
 
-Convenience header. Includes `core.hpp` and `macros.hpp`. This is the header
-that most users should use.
+*NOTE*: The two important headers are:
 
-### boost/openmethod/core.hpp
+* xref:#main[`boost/openmethod.hpp`] to define open-methods and overriders using
+convenient macros.
 
-Defines all the core constructs of the library: `method`, `virtual_ptr`,
-`use_classes`, `virtual_traits`, etc. Does not define any public macros apart
-from `BOOST_OPENMETHOD_DEFAULT_REGISTRY`. Users with a severe allergy to macros
-should use this header.
+* xref:#initialize[`boost/openmethod.hpp/initialize`] to initialize the library.
+Typically only included in the translation unit containing `main`.
 
-### boost/openmethod/macros.hpp
+The following headers make it possible to use standard smart pointers in virtual
+parameters:
 
-Defines all the public macros of the library, such as `BOOST_OPENMETHOD`,
-`BOOST_OPENMETHOD_CLASSES`, etc. This header includes `core.hpp`.
+* xref:#std_shared_ptr[`boost/openmethod/interop/std_shared_ptr.hpp`] to use
+`std::shared_ptr` in virtual parameters.
 
-### boost/openmethod/registry.hpp
+* xref:#std_unique_ptr[`boost/openmethod/interop/std_unique_ptr.hpp`] to use
+`std::unique_ptr` in virtual parameters.
 
-Defines `registry` and stock policies.
+*The other headers are for advanced use*.
 
-### boost/openmethod/default_registry.hpp
+### boost/openmethod/preamble.hpp
 
-### boost/openmethod/policies/default_error_handler.hpp
+Defines `registry` and stock policies. Also defines all the types and functions
+necessary to the definition of `registry`.
 
-### boost/openmethod/policies/fast_perfect_hash.hpp
+Most users should not include this header directly, unless for the purpose of
+overriding the default registry.
 
 ### boost/openmethod/policies/std_rtti.hpp
 
-### boost/openmethod/policies/static_rtti.hpp
+Includes all the headers above.
+
+Provides an implementation of the `rtti` policy using standard RTTI.
+
+### boost/openmethod/policies/fast_perfect_hash.hpp
+
+Includes all the headers above.
+
+Provides an implementation of the `hash` policy using a fast perfect hash
+function.
+
+### boost/openmethod/policies/vptr_vector.hpp
+
+Includes all the headers above.
+
+Provides an implementation of the `vptr` policy that stores the v-table pointers
+in a `std::vector` indexed by type ids, possibly hashed.
+
+### boost/openmethod/policies/default_error_handler.hpp
+
+Includes all the headers above.
+
+Provides an implementation of the `error_handler` policy that calls a
+`std::function<void(openmethod_error)>` when an error is encountered, and before
+the library aborts the program.
 
 ### boost/openmethod/policies/stderr_output.hpp
 
+Includes all the headers above.
+
+Provides an implementation of the `output` policy that writes diagnostics to
+the C standard error stream (not using iostreams).
+
+### boost/openmethod/default_registry.hpp
+
+Includes all the headers above.
+
+Defines the default registry, which contains all the stock policies listed
+above.
+
+Most users should not include this header directly, unless for the purpose of
+overriding the default registry.
+
+### boost/openmethod/core.hpp
+
+Includes all the headers above.
+
+Defines the main constructs of the library: methods, overriders and virtual
+pointers, and mechanisms to implement them. Does not define any public macros
+apart from `BOOST_OPENMETHOD_DEFAULT_REGISTRY`, if it is not defined already.
+
+Users with a severe allergy to macros can include this header.
+
+### boost/openmethod/macros.hpp
+
+Includes all the headers above.
+
+Defines the public macros of the library, such as `BOOST_OPENMETHOD`,
+`BOOST_OPENMETHOD_CLASSES`, etc.
+
+There is little point in including this header directly, as it has the same
+effect as including `boost/openmethod.hpp`, which is shorter.
+
+[#main]
+### boost/openmethod.hpp
+
+Includes all the headers above.
+
+This is the header that most users should include.
+
+### boost/openmethod/policies/static_rtti.hpp
+
+Includes `preamble.hpp`.
+
+Provides a minimal implementation of the `rtti` policy that does not depend on
+standard RTTI.
+
 ### boost/openmethod/policies/throw_error_handler.hpp
 
+Includes `preamble.hpp`.
+
+Provides an implementation of the `error_handler` policy that throws errors as
+exceptions.
+
 ### boost/openmethod/policies/vptr_map.hpp
 
-### boost/openmethod/policies/vptr_vector.hpp
+Includes `preamble.hpp`.
+
+Provides an implementation of the `vptr` policy that stores the v-table pointers
+in a map (by default a `std::map`) indexed by type ids.
 
+[#std_shared_ptr]
 ### boost/openmethod/interop/std_shared_ptr.hpp
 
+Includes `core.hpp`.
+
+Provides a `virtual_traits` specialization that make it possible to use a
+`std::shared_ptr` in place of a raw pointer or reference in virtual parameters.
+
+[#std_unique_ptr]
 ### boost/openmethod/interop/std_unique_ptr.hpp
+
+Includes `core.hpp`.
+
+Provides a `virtual_traits` specialization that make it possible to use a
+`std::unique_ptr` in place of a raw pointer or reference in virtual parameters.

include/boost/openmethod/core.hpp

@@ -20,7 +20,7 @@
 #include <boost/mp11/integral.hpp>
 #include <boost/mp11/list.hpp>
 
-#include <boost/openmethod/registry.hpp>
+#include <boost/openmethod/preamble.hpp>
 #include <boost/openmethod/default_registry.hpp>
 
 #ifndef BOOST_OPENMETHOD_DEFAULT_REGISTRY

include/boost/openmethod/default_registry.hpp

@@ -6,7 +6,7 @@
 #ifndef BOOST_OPENMETHOD_DEFAULT_REGISTRY_HPP
 #define BOOST_OPENMETHOD_DEFAULT_REGISTRY_HPP
 
-#include <boost/openmethod/registry.hpp>
+#include <boost/openmethod/preamble.hpp>
 #include <boost/openmethod/policies/std_rtti.hpp>
 #include <boost/openmethod/policies/vptr_vector.hpp>
 #include <boost/openmethod/policies/stderr_output.hpp>

include/boost/openmethod/initialize.hpp

@@ -7,7 +7,6 @@
 #define BOOST_OPENMETHOD_COMPILER_HPP
 
 #include <boost/openmethod/core.hpp>
-#include <boost/openmethod/options.hpp>
 #include <boost/openmethod/detail/ostdstream.hpp>
 
 #include <algorithm>

include/boost/openmethod/interop/std_shared_ptr.hpp

@@ -3,8 +3,8 @@
 // See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-#ifndef BOOST_OPENMETHOD_SHARED_PTR_HPP
-#define BOOST_OPENMETHOD_SHARED_PTR_HPP
+#ifndef BOOST_OPENMETHOD_INTEROP_SHARED_PTR_HPP
+#define BOOST_OPENMETHOD_INTEROP_SHARED_PTR_HPP
 
 #include <boost/openmethod/core.hpp>
 #include <memory>

include/boost/openmethod/interop/std_unique_ptr.hpp

@@ -3,8 +3,8 @@
 // See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-#ifndef BOOST_OPENMETHOD_UNIQUE_PTR_HPP
-#define BOOST_OPENMETHOD_UNIQUE_PTR_HPP
+#ifndef BOOST_OPENMETHOD_INTEROP_UNIQUE_PTR_HPP
+#define BOOST_OPENMETHOD_INTEROP_UNIQUE_PTR_HPP
 
 #include <boost/openmethod/core.hpp>
 

include/boost/openmethod/options.hpp

@@ -6,7 +6,7 @@
 #ifndef BOOST_OPENMETHOD_POLICY_VECTORED_ERROR_HPP
 #define BOOST_OPENMETHOD_POLICY_VECTORED_ERROR_HPP
 
-#include <boost/openmethod/registry.hpp>
+#include <boost/openmethod/preamble.hpp>
 
 #include <functional>
 #include <variant>