wip

Author: jll63

doc/modules/ROOT/pages/reference.adoc

@@ -134,7 +134,7 @@
 |===
 | Name
 | Description
-| xref:reference:boost/openmethod/boost_openmethod_vptr.adoc[`boost_openmethod_vptr`]
+| xref:reference:boost/openmethod/boost_openmethod_vptr-02.adoc[`boost_openmethod_vptr`]
 |
 | xref:reference:boost/openmethod/final_virtual_ptr-04.adoc[`final_virtual_ptr`]
 |

doc/tagfiles/boost-openmethod-doxygen.tag.xml

@@ -42,6 +42,7 @@
   <class kind="class">boost::openmethod::virtual_traits</class>
   <class kind="class">boost::openmethod::virtual_traits</class>
   <class kind="class">boost::openmethod::virtual_traits</class>
+  <class kind="class">boost::openmethod::boost_openmethod_vptr</class>
   <class kind="class">boost::openmethod::final_virtual_ptr</class>
   <class kind="class">boost::openmethod::is_method</class>
   <class kind="class">boost::openmethod::is_polymorphic</class>
@@ -63,13 +64,6 @@
     <anchor/>
     <arglist>(Class* )</arglist>
   </member>
-  <member kind="function">
-    <type>vptr_type</type>
-    <name>boost_openmethod_vptr</name>
-    <anchorfile>boost/openmethod/boost_openmethod_vptr.adoc</anchorfile>
-    <anchor/>
-    <arglist>(const Class&amp; obj, detail::inplace_vptr_registry&lt;Base1&gt;* registry)</arglist>
-  </member>
   <member kind="function">
     <type>void</type>
     <name>finalize</name>
@@ -416,7 +410,7 @@
     <name>operator[]</name>
     <anchorfile>boost/openmethod/compiler/operator_subs.adoc</anchorfile>
     <anchor/>
-    <arglist>(const openmethod::method&lt;Id, Signature, Registry&gt;&amp; fn)</arglist>
+    <arglist>(const openmethod::method&lt;Id, Signature, Registry&gt;&amp; )</arglist>
   </member>
   <member kind="function">
     <type>void</type>
@@ -914,6 +908,10 @@
     <arglist>(T* arg)</arglist>
   </member>
 </compound>
+<compound kind="class">
+  <name>boost::openmethod::boost_openmethod_vptr</name>
+  <filename>boost/openmethod/boost_openmethod_vptr-02.adoc</filename>
+</compound>
 <compound kind="class">
   <name>boost::openmethod::final_virtual_ptr</name>
   <filename>boost/openmethod/final_virtual_ptr-04.adoc</filename>

include/boost/openmethod/core.hpp

@@ -39,7 +39,7 @@ constexpr bool is_polymorphic = Registry::rtti::template is_polymorphic<Class>;
 
 template<
     class Class, class Registry = BOOST_OPENMETHOD_DEFAULT_REGISTRY,
-    typename Void = void>
+    typename = void>
 class virtual_ptr;
 
 // =============================================================================
@@ -280,6 +280,8 @@ struct use_classes {
     tuple_type tuple;
 };
 
+void boost_openmethod_vptr(...);
+
 // =============================================================================
 // virtual_ptr
 
@@ -309,8 +311,6 @@ struct is_virtual_ptr_aux<const virtual_ptr<Class, Registry, void>&>
 template<typename T>
 constexpr bool is_virtual_ptr = detail::is_virtual_ptr_aux<T>::value;
 
-void boost_openmethod_vptr(...);
-
 template<class Class, class Registry>
 constexpr bool has_vptr_fn = std::is_same_v<
     decltype(boost_openmethod_vptr(
@@ -390,18 +390,15 @@ inline auto final_virtual_ptr(Arg&& obj) {
 
 A wide pointer combining a pointer to an object and a pointer to its v-table.
 
-@par Template parameters
-- `Class`
-    The class of the object.
+@tparam Class The class of the object.
+
+@tparam Registry The registry in which `Class` is registered.
 
-- `Registry`
-    The registry in which `Class` is registered.
+@tparam unnamed Always `void` (used for SFINAE).
 
-- `Void`
-    Used for SFINAE in C++17. Not used in C++20 and later.
 */
 
-template<class Class, class Registry, typename Void>
+template<class Class, class Registry, typename>
 class virtual_ptr {
 
     using traits = virtual_traits<Class&, Registry>;
@@ -424,18 +421,52 @@ class virtual_ptr {
   public:
     using element_type = Class;
 
+    /**
+        Constructs a `virtual_ptr` with both object and v-table pointers
+        initialized to `nullptr`.
+    */
+
     virtual_ptr() = default;
 
+    /**
+        Constructs a `virtual_ptr` with both object and v-table pointers
+        initialized to `nullptr`.
+
+        @param value A `nullptr`.
+    */
+
     explicit virtual_ptr(std::nullptr_t)
         : vp(detail::box_vptr<use_indirect_vptrs>(detail::null_vptr)),
           obj(nullptr) {
     }
 
+    /**
+        Constructs a `virtual_ptr` pointing to an object of type `Other`.
+
+        The pointer to the v-table is obtained by calling
+        @ref boost_openmethod_vptr if a suitable overload exists, or the
+        @ref policies::vptr::fn::dynamic_vptr of the registry's @ref
+        policies::vptr otherwise.
+
+        @ref dynamic_vptr foo
+
+        @param other A `nullptr`.
+
+        @par Requirements
+
+        `Other` must be a polymorphic class, according to the `Registry`'s
+        `rtti` policy.
+
+        `Other*` must be convertible to `Class*`.
+
+        @par Errors
+    */
+
     template<
         class Other,
         typename = std::enable_if_t<
             std::is_constructible_v<Class*, Other*> &&
-            is_polymorphic<Class, Registry>>>
+            is_polymorphic<Other, Registry>>>
     virtual_ptr(Other& other)
         : vp(detail::box_vptr<use_indirect_vptrs>(
               detail::acquire_vptr<Registry>(other))),

include/boost/openmethod/registry.hpp

@@ -13,6 +13,45 @@ namespace boost::openmethod {
 
 namespace policies {
 
+/**
+    Base class for all policies.
+
+    A @e policy is a direct subclass of `policy`. Each such subclass
+
+    A @ref
+
+    @par Requirements
+
+    A policy must provide a typedef that identifies its category, which must be
+    a direct derived class of `policy`. The category identifies the policy in
+    the registry.
+
+    @code
+    using category = <policy direct derived class>;
+    @endcode
+
+    <policy_category> must be one of the following:
+
+    - `rtti` obtain static type information for a class, and dynamic type
+      information for an object.
+
+    - `error_handler`
+
+    - `type_hash`
+
+    - `vptr`
+
+    - `indirect_vptr`
+
+    - `output`
+
+    - `trace`
+
+    - `runtime_checks`
+
+    - `n2216`
+*/
+
 struct policy {};
 
 struct rtti : policy {
@@ -41,6 +80,25 @@ struct type_hash : policy {
     using category = type_hash;
 };
 
+/**
+    Acquires a v-table pointer for an object.
+
+    @par Requirements
+
+    Any implementation of this policy must provide a meta-function `fn` that
+    in the form of:
+
+    @code
+    template<class Registry>
+    struct fn {
+        template<class Class> static auto dynamic_vptr(const Class& arg) -> const vptr_type&;
+    };
+    @endcode
+
+    @see policies::vptr_vector::fn::dynamic_vptr for an example.
+
+*/
+
 struct vptr : policy {
     using category = vptr;
 };