Improve documentation of reshaped

3 files changed, 40 insertions, 8 deletions

diff --git a/Eigen/src/plugins/ReshapedMethods.h b/Eigen/src/plugins/ReshapedMethods.h
index 118841798..b22d8bb32 100644
--- a/Eigen/src/plugins/ReshapedMethods.h
+++ b/Eigen/src/plugins/ReshapedMethods.h
@@ -1,10 +1,13 @@
 
-/// \returns as expression of \c *this with reshaped sizes.
+/// \returns an expression of \c *this with reshaped sizes.
 ///
-/// \param nRows the number of rows in the reshaped expression, specified at either run-time or compile-time
-/// \param nCols the number of columns in the reshaped expression, specified at either run-time or compile-time
+/// \param nRows the number of rows in the reshaped expression, specified at either run-time or compile-time, or AutoSize
+/// \param nCols the number of columns in the reshaped expression, specified at either run-time or compile-time, or AutoSize
+/// \param order specifies whether the coefficients should be processed in column-major-order (ColOrder), in row-major-order (RowOrder),
+///              or follows the \em natural order of the nested expression (AutoOrder). The default is ColOrder.
 /// \tparam NRowsType the type of the value handling the number of rows, typically Index.
 /// \tparam NColsType the type of the value handling the number of columns, typically Index.
+/// \tparam OrderType the type of the order
 ///
 /// Dynamic size example: \include MatrixBase_reshaped_int_int.cpp
 /// Output: \verbinclude MatrixBase_reshaped_int_int.out
@@ -15,19 +18,39 @@
 /// \include MatrixBase_reshaped_fixed.cpp
 /// Output: \verbinclude MatrixBase_reshaped_fixed.out
 ///
-/// \sa class Reshaped, fix, fix<N>(int)
+/// Finally, one of the sizes parameter can be automatically deduced from the other one by passing AutoSize as in the following example:
+/// \include MatrixBase_reshaped_auto.cpp
+/// Output: \verbinclude MatrixBase_reshaped_auto.out
+/// AutoSize does preserve compile-time sizes when possible, i.e., when the sizes of the input are known at compile time \b and
+/// that the other size is passed at compile-time using Eigen::fix<N> as above.
+///
+/// \sa operator()(placeholders::all), class Reshaped, fix, fix<N>(int)
 ///
 #ifdef EIGEN_PARSED_BY_DOXYGEN
-template<typename NRowsType, typename NColsType, typename OrderType>
+template<typename NRowsType, typename NColsType, typename OrderType = ColOrder>
 EIGEN_DEVICE_FUNC
 inline Reshaped<Derived,...>
-reshaped(NRowsType nRows, NColsType nCols, OrderType = ColOrder);
+reshaped(NRowsType nRows, NColsType nCols, OrderType order = ColOrder);
 
 /** This is the const version of reshaped(NRowsType,NColsType). */
-template<typename NRowsType, typename NColsType, typename OrderType>
+template<typename NRowsType, typename NColsType, typename OrderType = ColOrder>
 EIGEN_DEVICE_FUNC
 inline const Reshaped<const Derived,...>
-reshaped(NRowsType nRows, NColsType nCols, OrderType = ColOrder) const;
+reshaped(NRowsType nRows, NColsType nCols, OrderType order = ColOrder) const;
+
+/// \returns as expression of \c *this with columns stacked to a linear column vector
+///
+/// This overload is essentially a shortcut for
+/// \code this->reshape(AutoSize,fix<1>) \endcode
+///
+/// Example:
+/// \include MatrixBase_reshaped_all.cpp
+/// Output: \verbinclude MatrixBase_reshaped_all.out
+///
+/// \sa reshaped()
+EIGEN_DEVICE_FUNC
+inline Reshaped<Derived,SizeAtCompileTime,1>
+operator()(placeholders::all);
 
 #else
 
diff --git a/doc/snippets/MatrixBase_reshaped_all.cpp b/doc/snippets/MatrixBase_reshaped_all.cpp
new file mode 100644
index 000000000..501f6276f
--- /dev/null
+++ b/doc/snippets/MatrixBase_reshaped_all.cpp
@@ -0,0 +1,5 @@
+using Eigen::placeholders::all;
+Matrix4i m = Matrix4i::Random();
+cout << "Here is the matrix m:" << endl << m << endl;
+cout << "Here is m(all).transpose():" << endl << m(all).transpose() << endl;
+cout << "Here is m.reshaped(fix<1>,AutoSize):" << endl << m.reshaped(fix<1>,AutoSize) << endl;
diff --git a/doc/snippets/MatrixBase_reshaped_auto.cpp b/doc/snippets/MatrixBase_reshaped_auto.cpp
new file mode 100644
index 000000000..8f02ae893
--- /dev/null
+++ b/doc/snippets/MatrixBase_reshaped_auto.cpp
@@ -0,0 +1,4 @@
+Matrix4i m = Matrix4i::Random();
+cout << "Here is the matrix m:" << endl << m << endl;
+cout << "Here is m.reshape(2, AutoSize):" << endl << m.reshaped(2, AutoSize) << endl;
+cout << "Here is m.reshape(AutoSize, fix<8>, RowOrder):" << endl << m.reshaped(AutoSize, fix<8>, RowOrder) << endl;