Merge pull request #64 from SylvainCorlay/documentation

Docstrings

Author: SylvainCorlay

docs/source/api_reference.rst

@@ -7,8 +7,19 @@
 API reference
 =============
 
+Containers
+----------
+
 .. toctree::
    :maxdepth: 2
 
    pyarray
    pytensor
+
+Numpy universal functions
+-------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   pyvectorize

include/xtensor-python/pyarray.hpp

@@ -64,7 +64,6 @@ namespace xt
     template <class A>
     class pyarray_backstrides
     {
-
     public:
 
         using array_type = A;
@@ -104,7 +103,13 @@ namespace xt
 
     /**
      * @class pyarray
-     * @brief Wrapper on the Python buffer protocol.
+     * @brief Multidimensional container providing the xtensor container semantics to a numpy array.
+     *
+     * pyarray is similar to the xarray container in that it has a dynamic dimensionality. Reshapes of
+     * a pyarray container are reflected in the underlying numpy array.
+     *
+     * @tparam T The type of the element stored in the pyarray.
+     * @sa pytensor
      */
     template <class T>
     class pyarray : public pycontainer<pyarray<T>>,
@@ -210,6 +215,10 @@ namespace xt
      * pyarray implementation *
      **************************/
 
+    /**
+     * @name Constructors
+     */
+    //@{
     template <class T>
     inline pyarray<T>::pyarray()
     {
@@ -220,6 +229,9 @@ namespace xt
         m_data[0] = T();
     }
 
+    /**
+     * Allocates a pyarray with nested initializer lists.
+     */
     template <class T>
     inline pyarray<T>::pyarray(const value_type& t)
     {
@@ -283,6 +295,12 @@ namespace xt
         init_from_python();
     }
 
+    /**
+     * Allocates an uninitialized pyarray with the specified shape and
+     * layout.
+     * @param shape the shape of the pyarray
+     * @param l the layout of the pyarray
+     */
     template <class T>
     inline pyarray<T>::pyarray(const shape_type& shape, layout l)
     {
@@ -291,6 +309,13 @@ namespace xt
         init_array(shape, strides);
     }
 
+    /**
+     * Allocates a pyarray with the specified shape and layout. Elements
+     * are initialized to the specified value.
+     * @param shape the shape of the pyarray
+     * @param value the value of the elements
+     * @param l the layout of the pyarray
+     */
     template <class T>
     inline pyarray<T>::pyarray(const shape_type& shape, const_reference value, layout l)
     {
@@ -300,32 +325,56 @@ namespace xt
         std::fill(m_data.begin(), m_data.end(), value);
     }
 
+    /**
+     * Allocates an uninitialized pyarray with the specified shape and strides.
+     * Elements are initialized to the specified value.
+     * @param shape the shape of the pyarray
+     * @param strides the strides of the pyarray
+     * @param value the value of the elements
+     */
     template <class T>
     inline pyarray<T>::pyarray(const shape_type& shape, const strides_type& strides, const_reference value)
     {
         init_array(shape, strides);
         std::fill(m_data.begin(), m_data.end(), value);
     }
 
+    /**
+     * Allocates an uninitialized pyarray with the specified shape and strides.
+     * @param shape the shape of the pyarray
+     * @param strides the strides of the pyarray
+     */
     template <class T>
     inline pyarray<T>::pyarray(const shape_type& shape, const strides_type& strides)
     {
         init_array(shape, strides);
     }
+    //@}
 
+    /**
+     * @name Extended copy semantic
+     */
+    //@{
+    /**
+     * The extended copy constructor.
+     */
     template <class T>
     template <class E>
     inline pyarray<T>::pyarray(const xexpression<E>& e)
     {
         semantic_base::assign(e);
     }
 
+    /**
+     * The extended assignment operator.
+     */
     template <class T>
     template <class E>
     inline auto pyarray<T>::operator=(const xexpression<E>& e) -> self_type&
     {
         return semantic_base::operator=(e);
     }
+    //@}
 
     template <class T>
     inline auto pyarray<T>::ensure(pybind11::handle h) -> self_type
@@ -397,8 +446,9 @@ namespace xt
     template <class T>
     inline auto pyarray<T>::backstrides_impl() const noexcept -> const inner_backstrides_type&
     {
-        // The pyarray object may be copied, invalidating m_backstrides. Building
-        // it each time it is needed avoids tricky bugs.
+        // m_backstrides wraps the numpy array backstrides, which is a raw pointer.
+        // The address of the raw pointer stored in the wrapper would be invalidated when the pyarray is copied.
+        // Hence, we build a new backstrides object (cheap wrapper around the underlying pointer) upon access.
         m_backstrides = backstrides_type(*this);
         return m_backstrides;
     }

include/xtensor-python/pycontainer.hpp

@@ -31,6 +31,16 @@
 namespace xt
 {
 
+    /**
+     * @class pycontainer
+     * @brief Base class for xtensor containers wrapping numpy arryays.
+     *
+     * The pycontainer class should not be instantiated directly. Instead, used should
+     * use pytensor and pyarray instancs.
+     *
+     * @tparam D The derived type, i.e. the inheriting class for which pycontainer
+     *           provides the interface.
+     */
     template <class D>
     class pycontainer : public pybind11::object,
                         public xcontainer<D>
@@ -191,6 +201,10 @@ namespace xt
         return reinterpret_cast<PyArrayObject*>(this->m_ptr);
     }
 
+    /**
+     * Reshapes the container.
+     * @param shape the new shape
+     */
     template <class D>
     inline void pycontainer<D>::reshape(const shape_type& shape)
     {
@@ -200,6 +214,11 @@ namespace xt
         }
     }
 
+    /**
+     * Reshapes the container.
+     * @param shape the new shape
+     * @param l the new layout
+     */
     template <class D>
     inline void pycontainer<D>::reshape(const shape_type& shape, layout l)
     {
@@ -208,6 +227,11 @@ namespace xt
         reshape(shape, strides);
     }
 
+    /**
+     * Reshapes the container.
+     * @param shape the new shape
+     * @param strides the new strides
+     */
     template <class D>
     inline void pycontainer<D>::reshape(const shape_type& shape, const strides_type& strides)
     {

include/xtensor-python/pytensor.hpp

@@ -81,6 +81,20 @@ namespace xt
         using temporary_type = pytensor<T, N>;
     };
 
+    /**
+     * @class pytensor
+     * @brief Multidimensional container providing the xtensor container semantics wrapping a numpy array.
+     *
+     * pytensor is similar to the xtensor container in that it has a static dimensionality.
+     *
+     * Unlike with the pyarray container, pytensor cannot be reshaped with a different number of dimensions
+     * and reshapes are not reflected on the Python side. However, pytensor has benefits compared to pyarray
+     * in terms of performances. pytensor shapes are stack-allocated which makes iteration upon pytensor
+     * faster than with pyarray.
+     *
+     * @tparam T The type of the element stored in the pyarray.
+     * @sa pyarray
+     */
     template <class T, std::size_t N>
     class pytensor : public pycontainer<pytensor<T, N>>,
                      public xcontainer_semantic<pytensor<T, N>>
@@ -158,6 +172,13 @@ namespace xt
      * pytensor implementation *
      ***************************/
 
+    /**
+     * @name Constructors
+     */
+    //@{
+    /**
+     * Allocates an uninitialized pytensor that holds 1 element.
+     */
     template <class T, std::size_t N>
     inline pytensor<T, N>::pytensor()
     {
@@ -167,6 +188,9 @@ namespace xt
         m_data[0] = T();
     }
 
+    /**
+     * Allocates a pytensor with a nested initializer list.
+     */
     template <class T, std::size_t N>
     inline pytensor<T, N>::pytensor(nested_initializer_list_t<T, N> t)
     {
@@ -195,13 +219,26 @@ namespace xt
         init_from_python();
     }
 
+    /**
+     * Allocates an uninitialized pytensor with the specified shape and
+     * layout.
+     * @param shape the shape of the pytensor
+     * @param l the layout of the pytensor
+     */
     template <class T, std::size_t N>
     inline pytensor<T, N>::pytensor(const shape_type& shape, layout l)
     {
         compute_strides(shape, l, m_strides);
         init_tensor(shape, m_strides);
     }
 
+    /**
+     * Allocates a pytensor with the specified shape and layout. Elements
+     * are initialized to the specified value.
+     * @param shape the shape of the pytensor
+     * @param value the value of the elements
+     * @param l the layout of the pytensor
+     */
     template <class T, std::size_t N>
     inline pytensor<T, N>::pytensor(const shape_type& shape,
                                     const_reference value,
@@ -212,6 +249,13 @@ namespace xt
         std::fill(m_data.begin(), m_data.end(), value);
     }
 
+    /**
+     * Allocates an uninitialized pytensor with the specified shape and strides.
+     * Elements are initialized to the specified value.
+     * @param shape the shape of the pytensor
+     * @param strides the strides of the pytensor
+     * @param value the value of the elements
+     */
     template <class T, std::size_t N>
     inline pytensor<T, N>::pytensor(const shape_type& shape,
                                     const strides_type& strides,
@@ -221,26 +265,43 @@ namespace xt
         std::fill(m_data.begin(), m_data.end(), value);
     }
 
+    /**
+     * Allocates an uninitialized pytensor with the specified shape and strides.
+     * @param shape the shape of the pytensor
+     * @param strides the strides of the pytensor
+     */
     template <class T, std::size_t N>
     inline pytensor<T, N>::pytensor(const shape_type& shape,
                                     const strides_type& strides)
     {
         init_tensor(shape, strides);
     }
-
+    //@}
+
+    /**
+     * @name Extended copy semantic
+     */
+    //@{
+    /**
+     * The extended copy constructor.
+     */
     template <class T, std::size_t N>
     template <class E>
     inline pytensor<T, N>::pytensor(const xexpression<E>& e)
     {
         semantic_base::assign(e);
     }
 
+    /**
+     * The extended assignment operator.
+     */
     template <class T, std::size_t N>
     template <class E>
     inline auto pytensor<T, N>::operator=(const xexpression<E>& e) -> self_type&
     {
         return semantic_base::operator=(e);
     }
+    //@}
 
     template <class T, std::size_t N>
     inline auto pytensor<T, N>::ensure(pybind11::handle h) -> self_type

include/xtensor-python/pyvectorize.hpp

@@ -33,12 +33,16 @@ namespace xt
         }
     };
 
+    /**
+     * @brief Create numpy universal function from scalar function.
+     */
     template <class R, class... Args>
     inline pyvectorizer<R(*)(Args...), R, Args...> pyvectorize(R(*f) (Args...))
     {
         return pyvectorizer<R(*) (Args...), R, Args...>(f);
     }
 
+    /// @cond DOXYGEN_INCLUDE_OVERLOADS
     template <class F, class R, class... Args>
     inline pyvectorizer<F, R, Args...> pyvectorize(F&& f, R(*) (Args...))
     {
@@ -50,6 +54,7 @@ namespace xt
     {
         return pyvectorize(std::forward<F>(f), (detail::get_function_type<F>*)nullptr);
     }
+    /// @endcond
 }
 
 #endif