Document Map and Stride, add examples.

Eigen/src/Array/Reverse.h

@@ -81,11 +81,11 @@ template<typename MatrixType, int Direction> class Reverse
 
     typedef typename MatrixType::template MakeBase< Reverse<MatrixType, Direction> >::Type Base;
     EIGEN_DENSE_PUBLIC_INTERFACE(Reverse)
+    using Base::IsRowMajor;
 
   protected:
     enum {
       PacketSize = ei_packet_traits<Scalar>::size,
-      IsRowMajor = MatrixType::IsRowMajor,
       IsColMajor = !IsRowMajor,
       ReverseRow = (Direction == Vertical)   || (Direction == BothDirections),
       ReverseCol = (Direction == Horizontal) || (Direction == BothDirections),

Eigen/src/Core/Map.h

@@ -33,10 +33,35 @@
   * \param MatrixType the equivalent matrix type of the mapped data
   * \param Options specifies whether the pointer is \c Aligned, or \c Unaligned.
   *                The default is \c Unaligned.
+  * \param StrideType optionnally specifies strides. By default, Map assumes the memory layout
+  *                   of an ordinary, contiguous array. This can be overridden by specifying strides.
+  *                   The type passed here must be a specialization of the Stride template, see examples below.
   *
   * This class represents a matrix or vector expression mapping an existing array of data.
   * It can be used to let Eigen interface without any overhead with non-Eigen data structures,
-  * such as plain C arrays or structures from other libraries.
+  * such as plain C arrays or structures from other libraries. By default, it assumes that the
+  * data is laid out contiguously in memory. You can however override this by explicitly specifying
+  * inner and outer strides.
+  *
+  * Here's an example of simply mapping a contiguous array as a column-major matrix:
+  * \include Map_simple.cpp
+  * Output: \verbinclude Map_simple.out
+  *
+  * If you need to map non-contiguous arrays, you can do so by specifying strides:
+  *
+  * Here's an example of mapping an array as a vector, specifying an inner stride, that is, the pointer
+  * increment between two consecutive coefficients. Here, we're specifying the inner stride as a compile-time
+  * fixed value.
+  * \include Map_inner_stride.cpp
+  * Output: \verbinclude Map_inner_stride.out
+  *
+  * Here's an example of mapping an array while specifying an outer stride. Here, since we're mapping
+  * as a column-major matrix, 'outer stride' means the pointer increment between two consecutive columns.
+  * Here, we're specifying the outer stride as a runtime parameter.
+  * \include Map_outer_stride.cpp
+  * Output: \verbinclude Map_outer_stride.out
+  *
+  * For more details and for an example of specifying both an inner and an outer stride, see class Stride.
   *
   * \b Tip: to change the array of data mapped by a Map object, you can use the C++
   * placement new syntax:
@@ -97,12 +122,30 @@ template<typename MatrixType, int Options, typename StrideType> class Map
            : this->rows();
     }
 
+    /** Constructor in the fixed-size case.
+      *
+      * \param data pointer to the array to map
+      * \param stride optional Stride object, passing the strides.
+      */
     inline Map(const Scalar* data, const StrideType& stride = StrideType())
       : Base(data), m_stride(stride) {}
 
+    /** Constructor in the dynamic-size vector case.
+      *
+      * \param data pointer to the array to map
+      * \param size the size of the vector expression
+      * \param stride optional Stride object, passing the strides.
+      */
     inline Map(const Scalar* data, int size, const StrideType& stride = StrideType())
       : Base(data, size), m_stride(stride) {}
 
+    /** Constructor in the dynamic-size matrix case.
+      *
+      * \param data pointer to the array to map
+      * \param rows the number of rows of the matrix expression
+      * \param cols the number of columns of the matrix expression
+      * \param stride optional Stride object, passing the strides.
+      */
     inline Map(const Scalar* data, int rows, int cols, const StrideType& stride = StrideType())
       : Base(data, rows, cols), m_stride(stride) {}
 

Eigen/src/Core/Stride.h

@@ -25,6 +25,32 @@
 #ifndef EIGEN_STRIDE_H
 #define EIGEN_STRIDE_H
 
+/** \class Stride
+  *
+  * \brief Holds strides information for Map
+  *
+  * This class holds the strides information for mapping arrays with strides with class Map.
+  *
+  * It holds two values: the inner stride and the outer stride.
+  *
+  * The inner stride is the pointer increment between two consecutive entries within a given row of a
+  * row-major matrix or within a given column of a column-major matrix.
+  *
+  * The outer stride is the pointer increment between two consecutive rows of a row-major matrix or
+  * between two consecutive columns of a column-major matrix.
+  *
+  * These two values can be passed either at compile-time as template parameters, or at runtime as
+  * arguments to the constructor.
+  *
+  * Indeed, this class takes two template parameters:
+  *  \param _OuterStrideAtCompileTime the outer stride, or Dynamic if you want to specify it at runtime.
+  *  \param _InnerStrideAtCompileTime the inner stride, or Dynamic if you want to specify it at runtime.
+  *
+  * \include Map_general_stride.cpp
+  * Output: \verbinclude Map_general_stride.out
+  *
+  * \sa class InnerStride, class OuterStride
+  */
 template<int _OuterStrideAtCompileTime, int _InnerStrideAtCompileTime>
 class Stride
 {
@@ -35,23 +61,28 @@ class Stride
       OuterStrideAtCompileTime = _OuterStrideAtCompileTime
     };
 
+    /** Default constructor, for use when strides are fixed at compile time */
     Stride()
       : m_outer(OuterStrideAtCompileTime), m_inner(InnerStrideAtCompileTime)
     {
       ei_assert(InnerStrideAtCompileTime != Dynamic && OuterStrideAtCompileTime != Dynamic);
     }
 
+    /** Constructor allowing to pass the strides at runtime */
     Stride(int outerStride, int innerStride)
       : m_outer(outerStride), m_inner(innerStride)
     {
       ei_assert(innerStride>=0 && outerStride>=0);
     }
 
+    /** Copy constructor */
     Stride(const Stride& other)
       : m_outer(other.outer()), m_inner(other.inner())
     {}
 
+    /** \returns the outer stride */
     inline int outer() const { return m_outer.value(); }
+    /** \returns the inner stride */
     inline int inner() const { return m_inner.value(); }
 
   protected:
@@ -59,6 +90,7 @@ class Stride
     ei_int_if_dynamic<InnerStrideAtCompileTime> m_inner;
 };
 
+/** \brief Convenience specialization of Stride to specify only an inner stride */
 template<int Value>
 class InnerStride : public Stride<0, Value>
 {
@@ -68,6 +100,7 @@ class InnerStride : public Stride<0, Value>
     InnerStride(int v) : Base(0, v) {}
 };
 
+/** \brief Convenience specialization of Stride to specify only an outer stride */
 template<int Value>
 class OuterStride : public Stride<Value, 0>
 {

unsupported/doc/examples/MatrixFunction.cpp

@@ -18,5 +18,5 @@ int main()
 
   std::cout << "The matrix A is:\n" << A << "\n\n";
   std::cout << "The matrix exponential of A is:\n" 
-	    << ei_matrix_function(A, expfn) << "\n\n";
+            << ei_matrix_function(A, expfn) << "\n\n";
 }