doc

Author: jll63

include/boost/openmethod/core.hpp

@@ -156,35 +156,24 @@ struct remove_virtual_aux<virtual_<T>> {
 template<typename T>
 using remove_virtual_ = typename remove_virtual_aux<T>::type;
 
-template<typename T, class Registry>
-using virtual_type = typename virtual_traits<T, Registry>::virtual_type;
-
-template<typename MethodArgList>
-using virtual_types = boost::mp11::mp_transform<
-    remove_virtual_, boost::mp11::mp_filter<detail::is_virtual, MethodArgList>>;
+template<typename T, class Registry, typename = void>
+struct virtual_type_aux {
+    using type = void;
+};
 
 template<typename T, class Registry>
-struct parameter_traits {
-    static auto peek(const T&) {
-        return nullptr;
-    }
-
-    template<typename>
-    static auto cast(T value) -> T {
-        return value;
-    }
+struct virtual_type_aux<
+    T, Registry,
+    std::void_t<typename virtual_traits<T, Registry>::virtual_type>> {
+    using type = typename virtual_traits<T, Registry>::virtual_type;
 };
 
 template<typename T, class Registry>
-struct parameter_traits<virtual_<T>, Registry> : virtual_traits<T, Registry> {};
+using virtual_type = typename virtual_type_aux<T, Registry>::type;
 
-template<class Class, class Registry>
-struct parameter_traits<virtual_ptr<Class, Registry, void>, Registry>
-    : virtual_traits<virtual_ptr<Class, Registry, void>, Registry> {};
-
-template<class Class, class Registry>
-struct parameter_traits<const virtual_ptr<Class, Registry, void>&, Registry>
-    : virtual_traits<const virtual_ptr<Class, Registry, void>&, Registry> {};
+template<typename MethodArgList>
+using virtual_types = boost::mp11::mp_transform<
+    remove_virtual_, boost::mp11::mp_filter<detail::is_virtual, MethodArgList>>;
 
 } // namespace detail
 
@@ -212,9 +201,7 @@ BOOST_OPENMETHOD_CLOSE_NAMESPACE_DETAIL_UNLESS_MRDOCS
 // virtual_traits
 
 template<typename T, class Registry>
-struct virtual_traits {
-    using virtual_type = void;
-};
+struct virtual_traits;
 
 template<typename T, class Registry>
 struct virtual_traits<T&, Registry> {
@@ -479,6 +466,26 @@ 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.
+//!
+//! @para 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.
+//! @tparam Arg The type of the argument.
+//! @param obj A reference to an object.
+//! @return A `virtual_ptr<Class, Registry>` pointing to `obj`.
 template<class Registry, typename Arg>
 inline auto final_virtual_ptr(Arg&& obj) {
     using namespace detail;
@@ -518,12 +525,25 @@ inline auto final_virtual_ptr(Arg&& obj) {
         std::forward<Arg>(obj));
 }
 
-//! Wide pointer combining a pointers to an object and its v-table
+//! Wide pointer combining pointers to an object and its v-table
+//!
+//! `virtual_ptr` is a wide pointer that combines a pointer to an object and a
+//! pointer to its v-table. It can be constructed from a reference, a pointer,
+//! or another `virtual_ptr`.
+//!
+//! Calls to methods via `virtual_ptr` are as fast as ordinary virtual function
+//! calls (typically two instructions).
+//!
+//! @par Requirements
+//!
+//! @li A `virtual_traits<Class&>` specialization must exist and provide the
+//! required members.
+//! @li `Class` must be a class type, possibly cv-qualified. It must be
+//! registered in `Registry`.
 //!
-//! @tparam Class The class of the object.
-//! @tparam Registry The registry in which `Class` is registered.
+//! @tparam Class The class of the object, possibly cv-qualified
+//! @tparam Registry The registry in which `Class` is registered
 //! @tparam unnamed Implementation defined, do not provide.
-
 template<class Class, class Registry, typename>
 class virtual_ptr {
 
@@ -549,6 +569,9 @@ class virtual_ptr {
     }
 
   public:
+    //! The type of the object pointed to
+    //!
+    //! This is the same as `Class`.
     using element_type = Class;
 
     //! Default constructor
@@ -794,25 +817,47 @@ class virtual_ptr {
         return *get();
     }
 
+    //! Cast to another `virtual_ptr` type
+    //! @tparam Other The target class of the cast
+    //! @return A `virtual_ptr<Other, Registry>` pointing to the same object
+    //! @par Requirements
+    //! @li `Other` must be a base or derived class of `Class`.
     template<class Other>
     auto cast() const -> decltype(auto) {
-        static_assert(
-            std::is_base_of_v<Class, Other> || std::is_base_of_v<Other, Class>);
-
         return virtual_ptr<Other, Registry>(
             traits::template cast<Other&>(*obj), vp);
     }
 
+    //! Construct a `virtual_ptr` from a reference to an object
+    //!
+    //! This function forwards to @ref final_virtual_ptr.
+    //!
+    //! @tparam Other The type of the argument
+    //! @param obj A reference to an object
+    //! @return A `virtual_ptr<Class, Registry>` pointing to `obj`
     template<class Other>
     static auto final(Other&& obj) {
         return final_virtual_ptr<Registry>(std::forward<Other>(obj));
     }
 
+    //! Get the v-table pointer
+    //! @return The v-table pointer
     auto vptr() const {
         return detail::unbox_vptr(this->vp);
     }
 };
 
+//! Wide pointer combining a smart pointer to an object and its v-table
+//!
+//! This specialization of `virtual_ptr` uses a smart pointer to the object,
+//! instead of a plain pointer.
+//!
+//! Calls to methods via `virtual_ptr` are as fast as ordinary virtual function
+//! calls (typically two instructions).
+//!
+//! @tparam Class The class of the object, possibly cv-qualified
+//! @tparam Registry The registry in which `Class` is registered
+//! @tparam unnamed Implementation defined, do not provide.
 template<class Class, class Registry>
 class virtual_ptr<
     Class, Registry,
@@ -1254,6 +1299,29 @@ template<class Registry>
 using method_base = std::conditional_t<
     Registry::has_deferred_static_rtti, deferred_method_info, method_info>;
 
+template<typename T, class Registry>
+struct parameter_traits {
+    static auto peek(const T&) {
+        return nullptr;
+    }
+
+    template<typename>
+    static auto cast(T value) -> T {
+        return value;
+    }
+};
+
+template<typename T, class Registry>
+struct parameter_traits<virtual_<T>, Registry> : virtual_traits<T, Registry> {};
+
+template<class Class, class Registry>
+struct parameter_traits<virtual_ptr<Class, Registry, void>, Registry>
+    : virtual_traits<virtual_ptr<Class, Registry, void>, Registry> {};
+
+template<class Class, class Registry>
+struct parameter_traits<const virtual_ptr<Class, Registry, void>&, Registry>
+    : virtual_traits<const virtual_ptr<Class, Registry, void>&, Registry> {};
+
 } // namespace detail
 
 //! Specialized with name, signature and return type
@@ -1613,8 +1681,8 @@ template<
 void method<Name, ReturnType(Parameters...), Registry>::resolve_type_ids() {
     using namespace detail;
     this->method_type_id = rtti::template static_type<method>();
-    this->return_type_id = rtti::template static_type<
-        typename virtual_traits<ReturnType, Registry>::virtual_type>();
+    this->return_type_id =
+        rtti::template static_type<virtual_type<ReturnType, Registry>>();
     init_type_ids<
         Registry,
         mp11::mp_transform_q<
@@ -1963,7 +2031,7 @@ void method<Name, ReturnType(Parameters...), Registry>::override_impl<
     using namespace detail;
 
     this->return_type = Registry::rtti::template static_type<
-        typename virtual_traits<FnReturnType, Registry>::virtual_type>();
+        virtual_type<FnReturnType, Registry>>();
     this->type = Registry::rtti::template static_type<decltype(Function)>();
     using Thunk = thunk<Function, decltype(Function)>;
     detail::

include/boost/openmethod/detail/types.hpp

@@ -87,31 +87,59 @@ struct hash_search_error : openmethod_error {
     auto write(Stream& os) const -> void;
 };
 
+//! An error indicating that no valid overrider exists for the given virtual
+//! tuple.
 struct call_error : openmethod_error {
+    //! The type_id of method that was called.
     type_id method;
+    //! The number of @em virtual arguments in the call.
     std::size_t arity;
+    //! The maximum size of `types`.
     static constexpr std::size_t max_types = 16;
+    //! The type_ids of the arguments.
     type_id types[max_types];
 
   protected:
     template<class Registry, class Stream>
     auto write_aux(Stream& os, const char* subtype) const -> void;
 };
 
+//! An error indicating that no overrider exists for the given virtual tuple.
+//!
+//! @see @ref call_error for data members.
 struct not_implemented_error : call_error {
+    //! Write a short description to an output stream.
+    //! @param os The output stream.
+    //! @tparam Registry The registry type.
+    //! @tparam Stream A @ref LightweightOutputStream.
     template<class Registry, class Stream>
     auto write(Stream& os) const -> void {
         write_aux<Registry>(os, "not implemented");
     }
 };
 
+//! An error indicating that a method call is ambiguous.
+//!
+//! @see @ref call_error for data members.
 struct ambiguous_error : call_error {
+    //! Write a short description to an output stream.
+    //! @param os The output stream.
+    //! @tparam Registry The registry type.
+    //! @tparam Stream A @ref LightweightOutputStream.
     template<class Registry, class Stream>
     auto write(Stream& os) const -> void {
         write_aux<Registry>(os, "ambiguous");
     }
 };
 
+//! Static and dynamic type mismatch in a "final" construct.
+//!
+//! If runtime checks are enabled, the "final" construct checks that the static
+//! and dynamic types of the object, as reported by the `rtti` policy,  are the
+//! same. If they are not, and if the registry contains an @ref error_handler
+//! policy, its @ref error function is called with a `final_error` object, then
+//! the program is terminated with
+//! @ref abort.
 struct final_error : openmethod_error {
     type_id static_type, dynamic_type;
 

include/boost/openmethod/registry.hpp

@@ -62,6 +62,18 @@ namespace boost::openmethod {
 //! and enabling some sections of code. They can be used as-is, without the need
 //! for subclassing.
 
+#ifdef __MRDOCS__
+
+//! Requirements for LightweightOutputStream (exposition only)
+struct LightweightOutputStream {
+    LightweightOutputStream& operator<<(const char* str);
+    LightweightOutputStream& operator<<(const std::string_view& view);
+    LightweightOutputStream& operator<<(const void* value);
+    LightweightOutputStream& operator<<(std::size_t value);
+};
+
+#endif
+
 namespace policies {
 
 #ifdef __MRDOCS__
@@ -79,14 +91,6 @@ struct Policy : PolicyCategory {
     struct fn;
 };
 
-//! Requirements for LightweightOutputStream (exposition only)
-struct LightweightOutputStream {
-    LightweightOutputStream& operator<<(const char* str);
-    LightweightOutputStream& operator<<(const std::string_view& view);
-    LightweightOutputStream& operator<<(const void* value);
-    LightweightOutputStream& operator<<(std::size_t value);
-};
-
 //! Requirements for IdsToVptr (exposition only)
 //!
 struct IdsToVptr {

test/test_core.cpp

@@ -45,9 +45,6 @@ static_assert(
 static_assert(std::is_same_v<
               virtual_traits<base&&, default_registry>::virtual_type, base>);
 
-static_assert(
-    std::is_same_v<virtual_traits<int, default_registry>::virtual_type, void>);
-
 static_assert(std::is_same_v<
               mp11::mp_filter<
                   is_virtual, mp11::mp_list<virtual_<a&>, b, virtual_<c&>>>,

test/test_n2216.cpp

@@ -45,6 +45,10 @@ BOOST_OPENMETHOD_OVERRIDE(
     return std::make_unique<matrix>();
 }
 
+static_assert(std::is_same_v<
+              detail::virtual_type<std::unique_ptr<matrix>, n2216>,
+              matrix>);
+
 BOOST_AUTO_TEST_CASE(covariant_return_type) {
     auto compiler = n2216::initialize();
     BOOST_TEST(compiler.report.ambiguous == 0u);

test/test_virtual_ptr_value_semantics.cpp

@@ -13,6 +13,9 @@ BOOST_AUTO_TEST_CASE_TEMPLATE(
     static_assert(
         std::is_same_v<
             typename virtual_ptr<Animal, Registry>::element_type, Animal>);
+    static_assert(std::is_same_v<
+                  typename virtual_ptr<const Animal, Registry>::element_type,
+                  const Animal>);
     static_assert(std::is_same_v<
                   decltype(std::declval<virtual_ptr<Animal, Registry>>().get()),
                   Animal*>);