From f1dc83975a17b9c007511aba397879b98d01ce85 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Fri, 18 Mar 2022 00:00:31 +0100 Subject: [PATCH] Fixed the documentation of adapt functions --- docs/Doxyfile | 2 +- docs/source/api/xarray_adaptor.rst | 19 +++- docs/source/api/xtensor_adaptor.rst | 34 -------- include/xtensor/xadapt.hpp | 130 +++++++++++++++++++++++++++- include/xtensor/xeval.hpp | 3 +- 5 files changed, 149 insertions(+), 39 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 456ed6d87..d0b8d6e08 100644 --- a/docs/Doxyfile +++ b/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 diff --git a/docs/source/api/xarray_adaptor.rst b/docs/source/api/xarray_adaptor.rst index 6764a445b..dc3112a9f 100644 --- a/docs/source/api/xarray_adaptor.rst +++ b/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&); + :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 diff --git a/docs/source/api/xtensor_adaptor.rst b/docs/source/api/xtensor_adaptor.rst index 8d02fd424..36d906f91 100644 --- a/docs/source/api/xtensor_adaptor.rst +++ b/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 diff --git a/include/xtensor/xadapt.hpp b/include/xtensor/xadapt.hpp index a79788e09..bf8150b1f 100644 --- a/include/xtensor/xadapt.hpp +++ b/include/xtensor/xadapt.hpp @@ -57,6 +57,8 @@ namespace xt using not_a_layout = xtl::negation>; } +#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(ptr), xtl::forward_sequence(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 + 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 + 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 > + 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 > + 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 + 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 + 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 + inline auto adapt(C&& pointer, const fixed_shape& /*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 + inline xtensor_adaptor 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 > + inline xtensor_adaptor, 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 * *****************************/ diff --git a/include/xtensor/xeval.hpp b/include/xtensor/xeval.hpp index e60b72ba7..84498c199 100644 --- a/include/xtensor/xeval.hpp +++ b/include/xtensor/xeval.hpp @@ -47,6 +47,7 @@ namespace xt { return std::forward(t); } + /// @endcond namespace detail { @@ -144,7 +145,6 @@ namespace xt return e; } - /// @cond DOXYGEN_INCLUDE_SFINAE template inline auto as_strided(E&& e) -> std::enable_if_t<(!(has_data_interface>::value @@ -154,6 +154,7 @@ namespace xt { return e; } + /// @endcond } #endif