improve doc

Author: jll63

doc/abstract_policy.adoc

@@ -14,5 +14,5 @@ struct abstract_policy {};
 ### Description
 
 `abstract_policy` is a required base class for a policy. It makes it possible
-for meta-functions such as `use_classes` to discriminate between user classes
+for metafunctions such as `use_classes` to discriminate between user classes
 and the (optional) policy class.

doc/html/index.html

@@ -4924,7 +4924,7 @@ <h4 id="virtual_ptr_synopsis_6">Synopsis</h4>
 <h4 id="virtual_ptr_description_6">Description</h4>
 <div class="paragraph">
 <p><code>abstract_policy</code> is a required base class for a policy. It makes it possible
-for meta-functions such as <code>use_classes</code> to discriminate between user classes
+for metafunctions such as <code>use_classes</code> to discriminate between user classes
 and the (optional) policy class.</p>
 </div>
 </div>

doc/modules/ROOT/pages/BOOST_OPENMETHOD.adoc

@@ -11,22 +11,71 @@ BOOST_OPENMETHOD(ID, (PARAMETERS...), RETURN_TYPE [, REGISTRY]);
 
 ### Description
 
-Declares a method.
+Declares a method, called `ID`, with the given `PARAMETERS` and `RETURN_TYPE`,
+and adds it to `REGISTRY`.
 
-The macro expands to several constructs:
+`PARAMETERS` is a comma-separated list of types, possibly followed by parameter
+names, just like in a function declaration. Parameters with a type in the form
+`virtual_ptr<T>` or `virtual_<T>` are called virtual parameters. The dynamic
+type of the arguments passed in virtual parameters determines which overrider to
+call, following the same rules as overloaded function resolution:
+
+1. Form the set of all applicable overriders. An overrider is applicable
+   if it can be called with the arguments passed to the method.
+2. If the set is empty, call the error handler (if present in the
+   registry), then terminate the program with `abort`.
+3. Remove the overriders that are dominated by other overriders in the
+   set. Overrider A dominates overrider B if any of its virtual formal
+   parameters is more specialized than B's, and if none of B's virtual
+   parameters is more specialized than A's.
+4. If the resulting set contains exactly one overrider, call it.
+
+If a single most specialized overrider does not exist, the program is
+terminated via `abort`. If the registry contains an `error_handler`
+policy, its `error` function is called with an object that describes the
+error, prior calling `abort`. `error` may prevent termination by throwing an
+exception.
+
+[]
+
+For each virtual argument `arg`, the dispatch mechanism calls
+`virtual_traits::peek(arg)` and deduces the v-table pointer from the
+`result`, using the first of the following methods that applies:
+
+1. If `result` is a `virtual_ptr`, get the pointer to the v-table from it.
+2. If `boost_openmethod_vptr` can be called with `result` and a `Registry*`,
+   and it returns a `vptr_type`, call it.
+3. Call `Registry::rtti::dynamic_vptr(result)`.
+
+
+The macro creates an ordinary inline function in the current scope, with the
+`virtual_` decorators removed from the parameter types. `virtual_ptr`{empty}s
+are preserved.
+
+NOTE: `ID` must be an *identifier*. Qualified names are not allowed.
+
+NOTE: The default value for `REGISTRY` is the value of
+`BOOST_OPENMETHOD_DEFAULT_REGISTRY` at the point `<boost/openmethod/core.hpp>` is
+included. Changing the value of this symbol has no effect after that point.
+
+### Implementation Notes
+
+The macro creates several additional constructs:
 
 * A `struct` forward declaration that acts as the method's identifier:
 
 ```c++
 struct BOOST_OPENMETHOD_ID(ID);
 ```
 
-* An inline function template, constrained to take the same `PARAMETERS`,
-  without the `virtual_` decorators, returning a `RETURN_TYPE`. The function
-  forwards to +
-  `method<BOOST_OPENMETHOD_ID(ID)(PARAMETERS...), RETURN_TYPE, REGISTRY>::fn`.
+* A class template declaration that acts as a container for the method's
+overriders in the current scope:
+
+```c++
+template<typename...> struct BOOST_OPENMETHOD_OVERRIDERS(NAME);
+```
 
-* A guide function used to match overriders with the method:
+* A _guide_ function used to match overriders with the method:
 
 ```c++
 auto BOOST_OPENMETHOD_ID(ID)_guide(...)
@@ -36,9 +85,3 @@ auto BOOST_OPENMETHOD_ID(ID)_guide(...)
 
 * A xref:BOOST_OPENMETHOD_REGISTER.adoc[registrar] that adds the method to the
 registry.
-
-NOTE: `ID` must be an *identifier*. Qualified names are not allowed.
-
-NOTE: The default value for `REGISTRY` is the value of
-`BOOST_OPENMETHOD_DEFAULT_REGISTRY` at the point `<boost/openmethod/core.hpp>` is
-included. Changing the value of this symbol has no effect after that point.

doc/modules/ROOT/pages/BOOST_OPENMETHOD_DECLARE_OVERRIDER.adoc

@@ -11,42 +11,47 @@ Defined in <boost/openmethod/macros.hpp>.
 
 ### Description
 
-Declares an overrider for a method.
+Declares an overrider for a method, but does not start its definition. This
+macro can be used in header files.
 
-The method is deduced from a call to a method guide function with the
-overrider's arguments.
+`ID` is the identifier of the method to which the overrider is added.
 
-The macro creates several entities in the current scope.
+NOTE: `ID` must be an *identifier*. Qualified names are not allowed.
 
-* A class template that acts as a container for the overriders of the methods
-called `NAME`:
+`PARAMETERS` is a comma-separated list of types, possibly followed by parameter
+names, just like in a function declaration.
+
+The macro tries to locate a method that can be called with the same argument
+list as the overrider, possibly via argument dependent lookup.
+
+Each `virtual_ptr<T>` in the method's parameter list must have a corresponding
+`virtual_ptr<U>` parameter in the same position in the overrider's parameter
+list, such that `U` is the same as `T`, or has `T` as an accessible unambiguous
+base.
+
+Each `virtual_<T>` in the method's parameter list must have a corresponding `U`
+parameter in the same position in the overrider's parameter list, such that `U`
+is the same as `T`, or has `T` as an accessible unambiguous base.
+
+### Implementation Notes
+
+The macro creates additional entities in the current scope.
+
+* A class template declaration that acts as a container for the method's
+overriders in the current scope:
 
 ```c++
-template<typename...> BOOST_OPENMETHOD_OVERRIDERS(NAME);
+template<typename...> struct BOOST_OPENMETHOD_OVERRIDERS(NAME);
 ```
 
-* A specialization of the container template for the overrider:
-
+* A specialization of the container for the overrider:
++
+--
 ```c++
-struct BOOST_OPENMETHOD_OVERRIDERS(NAME)<RETURN_TYPE(PARAMETERS...)> {
+struct BOOST_OPENMETHOD_OVERRIDERS(ID)<RETURN_TYPE(PARAMETERS...)> {
     static auto fn(PARAMETERS...) -> RETURN_TYPE;
     static auto has_next() -> bool;
     template<typename... Args>
     static auto next(typename... Args) -> RETURN_TYPE;
 };
 ```
-
-where:
-
-* `fn` is the overrider function.
-
-* `has_next()` returns `true` if a less specialized overrider exists.
-
-* `next(Args... args)` calls the next most specialized overrider via the
-pointer stored in the method's `next<fn>` member variable.
-
-`BOOST_OPENMETHOD_DECLARE_OVERRIDER` can be called in a header file, with a
-semicolon after the call. It can be called in a header file, but not multiple
-times in the same translation unit.
-
-NOTE: `NAME` must be an *identifier*. Qualified names are not allowed.

doc/modules/ROOT/pages/BOOST_OPENMETHOD_INLINE_OVERRIDE.adoc

@@ -16,4 +16,5 @@ BOOST_OPENMETHOD_INLINE_OVERRIDE(ID, (PARAMETERS...), RETURN_TYPE) {
 ### Description
 
 `BOOST_OPENMETHOD_INLINE_OVERRIDE` performs the same function as
-`BOOST_OPENMETHOD_OVERRIDE`, except that the overrider is defined inline.
+xref:BOOST_OPENMETHOD_OVERRIDE.adoc[BOOST_OPENMETHOD_OVERRIDE], except that the
+overrider is marked `inline`.

doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDE.adoc

@@ -17,19 +17,49 @@ BOOST_OPENMETHOD_OVERRIDE(ID, (PARAMETERS...), RETURN_TYPE) {
 
 `BOOST_OPENMETHOD_OVERRIDE` adds an overrider to a method.
 
-The method is deduced from a call to a method guide function with the
-overrider's arguments.
+`ID` is the identifier of the method to which the overrider is added.
 
-The macro creates several entities in the current scope.
+NOTE: `ID` must be an *identifier*. Qualified names are not allowed.
+
+`PARAMETERS` is a comma-separated list of types, possibly followed by parameter
+names, just like in a function declaration.
+
+The macro tries to locate a method that can be called with the same argument
+list as the overrider, possibly via argument dependent lookup.
+
+Each `virtual_ptr<T>` in the method's parameter list must have a corresponding
+`virtual_ptr<U>` parameter in the same position in the overrider's parameter
+list, such that `U` is the same as `T`, or has `T` as an accessible unambiguous
+base.
+
+Each `virtual_<T>` in the method's parameter list must have a corresponding `U`
+parameter in the same position in the overrider's parameter list, such that `U`
+is the same as `T`, or has `T` as an accessible unambiguous base.
+
+The following names are available inside the overrider's body:
+
+* `fn`: a pointer to a function, the overrider itself. Can be used for recursion.
+
+* `next`: a function with the same signature as the method (minus the
+`virtual_<>` decorators). It forwards to the next most specialized overrider, if
+it exists and it is unique. If the next overrider does not exist, or is
+ambiguous, calling `next` reports a cpp:no_overrider[] or a cpp:ambiguous_call[]
+and terminates the program.
+
+* `has_next()`: returns `true` if the next most specialized overrider exists.
 
-* A class template that acts as a container for the overriders of the methods
-called `ID`:
+### Implementation Notes
+
+The macro creates additional entities in the current scope.
+
+* A class template declaration that acts as a container for the method's
+overriders in the current scope:
 
 ```c++
-template<typename...> BOOST_OPENMETHOD_OVERRIDERS(ID);
+template<typename...> struct BOOST_OPENMETHOD_OVERRIDERS(NAME);
 ```
 
-* A specialization of the container template for the overrider:
+* A specialization of the container for the overrider:
 +
 --
 ```c++
@@ -40,15 +70,6 @@ struct BOOST_OPENMETHOD_OVERRIDERS(ID)<RETURN_TYPE(PARAMETERS...)> {
     static auto next(typename... Args) -> RETURN_TYPE;
 };
 ```
-where:
-
-* `fn` is the overrider function.
-
-* `has_next()` returns `true` if a less specialized overrider exists.
-
-* `next(Args... args)` calls the next most specialized overrider via the
-pointer stored in the method's `next<fn>` member variable.
---
 
 []
 
@@ -66,5 +87,3 @@ auto BOOST_OPENMETHOD_OVERRIDERS(ID)<RETURN_TYPE(PARAMETERS...)>::fn(
 {empty}
 
 The `{}` block following the call to the macro is the body of the function.
-
-NOTE: `ID` must be an *identifier*. Qualified names are not allowed.

include/boost/openmethod/core.hpp

@@ -402,11 +402,8 @@ using use_classes_tuple_type = boost::mp11::mp_apply<
 //! such object per class. The only such case known to the author is when using
 //! Windows DLLs.
 //!
-//! Virtual and multiple inheritance are supported, as long as it is possible to
-//! cast the virtual arguments of a method call to the types required by the
-//! overriders. The registry's `rtti` policy defines which casts are possible.
-//! For the @ref policies::std_rtti (the default), some scenarios involving
-//! repeated inheritance may not allow the cast.
+//! Virtual and multiple inheritance are supported, with the exclusion of
+//! repeated inheritance.
 template<class... Classes>
 class use_classes {
     detail::use_classes_tuple_type<Classes...> tuple;
@@ -2084,7 +2081,7 @@ struct validate_method_parameter<
 //!    if it can be called with the arguments passed to the method.
 //!
 //! 2. If the set is empty, call the error handler (if present in the
-//!    policy), then terminate the program with `abort`.
+//!    registry), then terminate the program with `abort`.
 //!
 //! 3. Remove the overriders that are dominated by other overriders in the
 //!    set. Overrider A dominates overrider B if any of its virtual formal
@@ -2235,13 +2232,14 @@ class method<Id, ReturnType(Parameters...), Registry>
     //! @li Have the same number of formal parameters as the method.
     //!
     //! @li Each `virtual_ptr<T>` in the method's parameter list must have a
-    //! corresponding `virtual_ptr<U> in the same position in the overrider's
-    //! parameter list. The registry's `rtti` policy must have a
-    //! `dynamic_cast_ref` that can cast `virtual_ptr<T>` to `virtual_ptr<U>`.
+    //! corresponding `virtual_ptr<U>` parameter in the same position in the
+    //! overrider's parameter list, such that `U` is the same as `T`, or has
+    //! `T` as an accessible unambiguous base.
     //!
     //! @li Each `virtual_<T>` in the method's parameter list must have a
-    //! corresponding parameter `U` that the registry's `rtti` policy can cast
-    //! from `T` to `U`. Note: `U` must *not* be decorated with `virtual_<>`.
+    //! corresponding `U` parameter in the same position in the overrider's
+    //! parameter list, such that `U` is the same as `T`, or has `T` as an
+    //! accessible unambiguous base.
     //!
     //! @li All other formal parameters must have the same type as the method's
     //! corresponding parameters.

include/boost/openmethod/policies/default_error_handler.hpp

@@ -32,7 +32,7 @@ namespace boost::openmethod::policies {
 //! enable exception throwing on a registry basis.
 
 struct default_error_handler : error_handler {
-    //! A model of @ref error_handler::fn.
+    //! A ErrorHandlerFn metafunction.
     //!
     //! @tparam Registry The registry containing this policy.
     template<class Registry>

include/boost/openmethod/policies/fast_perfect_hash.hpp

@@ -37,7 +37,7 @@ std::vector<type_id> fast_perfect_hash_control;
 
 namespace policies {
 
-//! Hash a @ref type_id using a fast, perfect hash function
+//! Hash type ids using a fast, perfect hash function.
 //!
 //! `fast_perfect_hash` implements the @ref type_hash policy using a hash
 //! function in the form `H(x)=(M*x)>>S`. It attempts to determine values for
@@ -68,7 +68,7 @@ struct fast_perfect_hash : type_hash {
 
     using errors = std::variant<search_error>;
 
-    //! A model of @ref type_hash::fn.
+    //! A TypeHashFn metafunction.
     //!
     //! @tparam Registry The registry containing this policy
     template<class Registry>

include/boost/openmethod/policies/static_rtti.hpp

@@ -23,7 +23,7 @@ namespace boost::openmethod::policies {
 //! TODO
 //! include::example$static_rtti.cpp[tag=all]
 struct static_rtti : rtti {
-    //! A (partial) model of @ref rtti::fn.
+    //! A RttiFn metafunction.
     //!
     //! @tparam Registry The registry containing this policy.
     template<class Registry>