Merge pull request #2496 from JohanMabille/adapt_doc

Fixed the documentation of adapt functions

Author: JohanMabille

docs/Doxyfile

@@ -1,6 +1,6 @@
 PROJECT_NAME = "xtensor"
 XML_OUTPUT = xml
-INPUT = missing_macro.hpp ../include
+INPUT = ../include
 GENERATE_LATEX = NO
 GENERATE_MAN = NO
 GENERATE_RTF = NO

docs/source/api/xarray_adaptor.rst

@@ -13,8 +13,8 @@ Defined in ``xtensor/xarray.hpp``
    :project: xtensor
    :members:
 
-adapt (xarray_adaptor)
-=======================
+adapt
+=====
 
 Defined in ``xtensor/xadapt.hpp``
 
@@ -36,8 +36,23 @@ Defined in ``xtensor/xadapt.hpp``
 .. doxygenfunction:: xt::adapt(T (&)[N], SC&&, SS&&)
    :project: xtensor
 
+.. doxygenfunction:: xt::adapt(C&& pointer, const fixed_shape<X...>&);
+   :project: xtensor
+
+.. doxygenfunction:: xt::adapt(C&&, layout_type)
+   :project: xtensor
+
+.. doxygenfunction:: xt::adapt(P&&, typename A::size_type, O, layout_type, const A&)
+   :project: xtensor
+
 .. doxygenfunction:: xt::adapt_smart_ptr(P&&, const SC&, layout_type)
    :project: xtensor
 
 .. doxygenfunction:: xt::adapt_smart_ptr(P&&, const SC&, D&&, layout_type)
    :project: xtensor
+
+.. doxygenfunction:: xt::adapt_smart_ptr(P&&, const I (&)[N], layout_type)
+   :project: xtensor
+
+.. doxygenfunction:: xt::adapt_smart_ptr(P&&, const I (&)[N], D&&, layout_type)
+   :project: xtensor

docs/source/api/xtensor_adaptor.rst

@@ -13,37 +13,3 @@ Defined in ``xtensor/xtensor.hpp``
    :project: xtensor
    :members:
 
-adapt (xtensor_adaptor)
-========================
-
-Defined in ``xtensor/xadapt.hpp``
-
-.. doxygenfunction:: xt::adapt(C&&, layout_type)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(C&&, const SC&, layout_type)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(C&&, SC&&, SS&&)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(P&&, typename A::size_type, O, layout_type, const A&)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(P&&, typename A::size_type, O, const SC&, layout_type, const A&)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(P&&, typename A::size_type, O, SC&&, SS&&, const A&)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(T (&)[N], const SC&, layout_type)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt(T (&)[N], SC&&, SS&&)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt_smart_ptr(P&&, const I (&)[N], layout_type)
-   :project: xtensor
-
-.. doxygenfunction:: xt::adapt_smart_ptr(P&&, const I (&)[N], D&&, layout_type)
-   :project: xtensor

include/xtensor/xadapt.hpp

@@ -57,6 +57,8 @@ namespace xt
         using not_a_layout = xtl::negation<std::is_same<layout_type,T>>;
     }
 
+#ifndef IN_DOXYGEN
+
     /**************************
      * xarray_adaptor builder *
      **************************/
@@ -202,7 +204,7 @@ namespace xt
     /***************************
      * xtensor_adaptor builder *
      ***************************/
-
+    
     /**
      * Constructs a 1-D xtensor_adaptor of the given stl-like container,
      * with the specified layout_type.
@@ -403,6 +405,132 @@ namespace xt
         return adapt(std::forward<C>(ptr), xtl::forward_sequence<shape_type, decltype(shape)>(shape));
     }
 
+#else // IN_DOXYGEN
+
+    /**
+     * Constructs:
+     * - an xarray_adaptor if SC is not an array type
+     * - an xtensor_adaptor if SC is an array type
+     *
+     * from the given stl-like container or pointer, with the specified shape and layout.
+     * If the adaptor is built from a pointer, it does not take its ownership.
+     * @param container the container or pointer to adapt
+     * @param shape the shape of the adaptor
+     * @param l the layout_type of the adaptor
+     */
+    template <layout_type L = XTENSOR_DEFAULT_LAYOUT, class C, class SC>
+    inline auto adapt(C&& container, const SC& shape, layout_type l = L);
+
+    /**
+     * Constructs:
+     * - an xarray_adaptor if SC is not an array type
+     * - an xtensor_adaptor if SC is an array type
+     *
+     * from the given stl-like container with the specified shape and strides.
+     * @param container the container to adapt
+     * @param shape the shape of the adaptor
+     * @param strides the strides of the adaptor
+     */
+    template <class C, class SC, class SS>
+    inline auto adapt(C&& container, SC&& shape, SS&& strides);
+
+    /**
+     * Constructs:
+     * - an xarray_adaptor if SC is not an array type
+     * - an xtensor_adaptor if SC is an array type
+     * 
+     * of the given dynamically allocated C array, with the specified shape and layout.
+     * @param pointer the pointer to the beginning of the dynamic array
+     * @param size the size of the dynamic array
+     * @param ownership indicates whether the adaptor takes ownership of the array.
+     *        Possible values are ``no_ownership()`` or ``acquire_ownership()``
+     * @param shape the shape of the adaptor
+     * @param l the layout_type of the adaptor
+     * @param alloc the allocator used for allocating / deallocating the dynamic array
+     */
+    template <layout_type L = XTENSOR_DEFAULT_LAYOUT, class P, class O, class SC, class A = detail::default_allocator_for_ptr_t<P>>
+    inline auto
+    adapt(P&& pointer, typename A::size_type size, O ownership, const SC& shape, layout_type l = L, const A& alloc = A());
+
+    /**
+     * Constructs:
+     * - an xarray_adaptor if SC is not an array type
+     * - an xtensor_adaptor if SC is an array type
+     *
+     * of the given dynamically allocated C array, with the specified shape and strides.
+     * @param pointer the pointer to the beginning of the dynamic array
+     * @param size the size of the dynamic array
+     * @param ownership indicates whether the adaptor takes ownership of the array.
+     *        Possible values are ``no_ownership()`` or ``acquire_ownership()``
+     * @param shape the shape of the adaptor
+     * @param strides the strides of the adaptor
+     * @param alloc the allocator used for allocating / deallocating the dynamic array
+     */
+    template <class P, class O, class SC, class SS, class A = detail::default_allocator_for_ptr_t<P>>
+    inline auto
+    adapt(P&& pointer, typename A::size_type size, O ownership, SC&& shape, SS&& strides, const A& alloc = A());
+
+    /**
+     * Contructs:
+     * - an xarray_adaptor if SC is not an array type
+     * - an xtensor_adaptor if SC is an array type
+     *
+     * of the given C array allocated on the stack, with the specified shape and layout.
+     * @param c_array the C array allocated on the stack
+     * @param shape the shape of the adaptor
+     * @param l the layout_type of the adaptor
+     */
+    template <layout_type L = XTENSOR_DEFAULT_LAYOUT, class T, std::size_t N, class SC>
+    inline auto adapt(T (&c_array)[N], const SC& shape, layout_type l = L);
+
+    /**
+     * Contructs:
+     * - an xarray_adaptor if SC is not an array type
+     * - an xtensor_adaptor if SC is an array type
+     *
+     * of the given C array allocated on the stack, with the
+     * specified shape and strides.
+     * @param c_array the C array allocated on the stack
+     * @param shape the shape of the adaptor
+     * @param strides the strides of the adaptor
+     */
+    template <class T, std::size_t N, class SC, class SS>
+    inline auto adapt(T (&c_array)[N], SC&& shape, SS&& strides);
+
+    /**
+     * Constructs an non-owning xtensor_fixed_adaptor from a pointer with the
+     * specified shape and layout.
+     * @param pointer the pointer to adapt
+     * @param shape the shape of the xtensor_fixed_adaptor
+     */
+    template <layout_type L = XTENSOR_DEFAULT_LAYOUT, class C, std::size_t... X>
+    inline auto adapt(C&& pointer, const fixed_shape<X...>& /*shape*/);
+
+    /**
+     * Constructs a 1-D xtensor_adaptor of the given stl-like container,
+     * with the specified layout_type.
+     * @param container the container to adapt
+     * @param l the layout_type of the xtensor_adaptor
+     */
+    template <layout_type L = XTENSOR_DEFAULT_LAYOUT, class C>
+    inline xtensor_adaptor<C, 1, L> adapt(C&& container, layout_type l = L);
+
+    /**
+     * Constructs a 1-D xtensor_adaptor of the given dynamically allocated C array,
+     * with the specified layout.
+     * @param pointer the pointer to the beginning of the dynamic array
+     * @param size the size of the dynamic array
+     * @param ownership indicates whether the adaptor takes ownership of the array.
+     *        Possible values are ``no_ownership()`` or ``acquire_ownership()``
+     * @param l the layout_type of the xtensor_adaptor
+     * @param alloc the allocator used for allocating / deallocating the dynamic array
+     */
+    template <layout_type L = XTENSOR_DEFAULT_LAYOUT, class P, class O, class A = detail::default_allocator_for_ptr_t<P>>
+    inline xtensor_adaptor<xbuffer_adaptor<xtl::closure_type_t<P>, O, A>, 1, L>
+    adapt(P&& pointer, typename A::size_type size, O ownership, layout_type l = L, const A& alloc = A());
+
+#endif // IN_DOXYGEN
+
     /*****************************
      * smart_ptr adapter builder *
      *****************************/

include/xtensor/xeval.hpp

@@ -47,6 +47,7 @@ namespace xt
     {
         return std::forward<T>(t);
     }
+    /// @endcond
 
     namespace detail
     {
@@ -144,7 +145,6 @@ namespace xt
         return e;
     }
 
-    /// @cond DOXYGEN_INCLUDE_SFINAE
     template <layout_type L = layout_type::any, class E>
     inline auto as_strided(E&& e)
         -> std::enable_if_t<(!(has_data_interface<std::decay_t<E>>::value
@@ -154,6 +154,7 @@ namespace xt
     {
         return e;
     }
+    /// @endcond
 }
 
 #endif