more documentation, 12 more code snippets

Eigen/Core

@@ -1,6 +1,6 @@
-#include <iostream>
 #include <complex>
 #include <cassert>
+#include <iostream>
 
 namespace Eigen {
 

Eigen/src/Core/IO.h

@@ -26,6 +26,10 @@
 #ifndef EIGEN_IO_H
 #define EIGEN_IO_H
 
+/** \relates MatrixBase
+  *
+  * Outputs the matrix, laid out as an array as usual, to the given stream.
+  */
 template<typename Scalar, typename Derived>
 std::ostream & operator <<
 ( std::ostream & s,

Eigen/src/Core/Map.h

@@ -26,6 +26,19 @@
 #ifndef EIGEN_MAP_H
 #define EIGEN_MAP_H
 
+/** \class Map
+  *
+  * \brief A matrix or vector expression mapping an existing array of data.
+  *
+  * 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.
+  *
+  * This class is the return type of Matrix::map() and most of the time this is the only
+  * way it is used.
+  *
+  * \sa Matrix::map()
+  */
 template<typename MatrixType> class Map
   : public MatrixBase<typename MatrixType::Scalar, Map<MatrixType> >
 {
@@ -75,6 +88,7 @@ template<typename MatrixType> class Map
     int m_rows, m_cols;
 };
 
+/** This is the const version of map(Scalar*,int,int). */
 template<typename _Scalar, int _Rows, int _Cols, MatrixStorageOrder _StorageOrder>
 const Map<Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >
 Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(const Scalar* data, int rows, int cols)
@@ -82,6 +96,7 @@ Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(const Scalar* data, int rows,
   return Map<Matrix>(data, rows, cols);
 }
 
+/** This is the const version of map(Scalar*,int). */
 template<typename _Scalar, int _Rows, int _Cols, MatrixStorageOrder _StorageOrder>
 const Map<Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >
 Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(const Scalar* data, int size)
@@ -93,6 +108,7 @@ Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(const Scalar* data, int size)
     return Map<Matrix>(data, 1, size);
 }
 
+/** This is the const version of map(Scalar*). */
 template<typename _Scalar, int _Rows, int _Cols, MatrixStorageOrder _StorageOrder>
 const Map<Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >
 Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(const Scalar* data)
@@ -100,6 +116,15 @@ Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(const Scalar* data)
   return Map<Matrix>(data, _Rows, _Cols);
 }
 
+/** \returns a expression of a matrix or vector mapping the given data.
+  *
+  * \param data The array of data to map
+  * \param rows The number of rows of the expression to construct
+  * \param cols The number of columns of the expression to construct
+  *
+  * Example: \include MatrixBase_map_int_int.cpp
+  * Output: \verbinclude MatrixBase_map_int_int.out
+  */
 template<typename _Scalar, int _Rows, int _Cols, MatrixStorageOrder _StorageOrder>
 Map<Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >
 Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(Scalar* data, int rows, int cols)
@@ -107,6 +132,16 @@ Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(Scalar* data, int rows, int co
   return Map<Matrix>(data, rows, cols);
 }
 
+/** \returns a expression of a vector mapping the given data.
+  *
+  * \param data The array of data to map
+  * \param rows The size (number of coefficients) of the expression to construct
+  *
+  * \only_for_vectors
+  *
+  * Example: \include MatrixBase_map_int.cpp
+  * Output: \verbinclude MatrixBase_map_int.out
+  */
 template<typename _Scalar, int _Rows, int _Cols, MatrixStorageOrder _StorageOrder>
 Map<Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >
 Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(Scalar* data, int size)
@@ -118,6 +153,13 @@ Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(Scalar* data, int size)
     return Map<Matrix>(data, 1, size);
 }
 
+/** \returns a expression of a fixed-size matrix or vector mapping the given data.
+  *
+  * \param data The array of data to map
+  *
+  * Example: \include MatrixBase_map.cpp
+  * Output: \verbinclude MatrixBase_map.out
+  */
 template<typename _Scalar, int _Rows, int _Cols, MatrixStorageOrder _StorageOrder>
 Map<Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >
 Matrix<_Scalar, _Rows, _Cols, _StorageOrder>::map(Scalar* data)

Eigen/src/Core/Matrix.h

@@ -26,6 +26,7 @@
 #ifndef EIGEN_MATRIX_H
 #define EIGEN_MATRIX_H
 
+/** \class Matrix */
 template<typename _Scalar, int _Rows, int _Cols,
          MatrixStorageOrder _StorageOrder = EIGEN_DEFAULT_MATRIX_STORAGE_ORDER>
 class Matrix : public MatrixBase<_Scalar, Matrix<_Scalar, _Rows, _Cols, _StorageOrder> >,

Eigen/src/Core/Ones.h

@@ -26,6 +26,12 @@
 #ifndef EIGEN_ONES_H
 #define EIGEN_ONES_H
 
+/** \class Ones
+  *
+  * \brief Expression of a matrix where all coefficients equal one.
+  *
+  * \sa MatrixBase::ones(), MatrixBase::ones(int), MatrixBase::ones(int,int)
+  */
 template<typename MatrixType> class Ones : NoOperatorEquals,
   public MatrixBase<typename MatrixType::Scalar, Ones<MatrixType> >
 {
@@ -59,12 +65,42 @@ template<typename MatrixType> class Ones : NoOperatorEquals,
     int m_rows, m_cols;
 };
 
+/** \returns an expression of a matrix where all coefficients equal one.
+  *
+  * The parameters \a rows and \a cols are the number of rows and of columns of
+  * the returned matrix. Must be compatible with this MatrixBase type.
+  *
+  * This variant is meant to be used for dynamic-size matrix types. For fixed-size types,
+  * it is redundant to pass \a rows and \a cols as arguments, so ones() should be used
+  * instead.
+  *
+  * Example: \include MatrixBase_ones_int_int.cpp
+  * Output: \verbinclude MatrixBase_ones_int_int.out
+  *
+  * \sa ones(), ones(int)
+  */
 template<typename Scalar, typename Derived>
 const Ones<Derived> MatrixBase<Scalar, Derived>::ones(int rows, int cols)
 {
   return Ones<Derived>(rows, cols);
 }
 
+/** \returns an expression of a vector where all coefficients equal one.
+  *
+  * The parameter \a size is the size of the returned vector.
+  * Must be compatible with this MatrixBase type.
+  *
+  * \only_for_vectors
+  *
+  * This variant is meant to be used for dynamic-size vector types. For fixed-size types,
+  * it is redundant to pass \a size as argument, so ones() should be used
+  * instead.
+  *
+  * Example: \include MatrixBase_ones_int.cpp
+  * Output: \verbinclude MatrixBase_ones_int.out
+  *
+  * \sa ones(), ones(int,int)
+  */
 template<typename Scalar, typename Derived>
 const Ones<Derived> MatrixBase<Scalar, Derived>::ones(int size)
 {
@@ -73,6 +109,16 @@ const Ones<Derived> MatrixBase<Scalar, Derived>::ones(int size)
   else return Ones<Derived>(size, 1);
 }
 
+/** \returns an expression of a fixed-size matrix or vector where all coefficients equal one.
+  *
+  * This variant is only for fixed-size MatrixBase types. For dynamic-size types, you
+  * need to use the variants taking size arguments.
+  *
+  * Example: \include MatrixBase_ones.cpp
+  * Output: \verbinclude MatrixBase_ones.out
+  *
+  * \sa ones(int), ones(int,int)
+  */
 template<typename Scalar, typename Derived>
 const Ones<Derived> MatrixBase<Scalar, Derived>::ones()
 {

Eigen/src/Core/Random.h

@@ -26,6 +26,12 @@
 #ifndef EIGEN_RANDOM_H
 #define EIGEN_RANDOM_H
 
+/** \class Random
+  *
+  * \brief Expression of a random matrix or vector.
+  *
+  * \sa MatrixBase::random(), MatrixBase::random(int), MatrixBase::random(int,int)
+  */
 template<typename MatrixType> class Random : NoOperatorEquals,
   public MatrixBase<typename MatrixType::Scalar, Random<MatrixType> >
 {
@@ -59,12 +65,42 @@ template<typename MatrixType> class Random : NoOperatorEquals,
     int m_rows, m_cols;
 };
 
+/** \returns a random matrix (not an expression, the matrix is immediately evaluated).
+  *
+  * The parameters \a rows and \a cols are the number of rows and of columns of
+  * the returned matrix. Must be compatible with this MatrixBase type.
+  *
+  * This variant is meant to be used for dynamic-size matrix types. For fixed-size types,
+  * it is redundant to pass \a rows and \a cols as arguments, so random() should be used
+  * instead.
+  *
+  * Example: \include MatrixBase_random_int_int.cpp
+  * Output: \verbinclude MatrixBase_random_int_int.out
+  *
+  * \sa random(), random(int)
+  */
 template<typename Scalar, typename Derived>
 const Eval<Random<Derived> > MatrixBase<Scalar, Derived>::random(int rows, int cols)
 {
   return Random<Derived>(rows, cols).eval();
 }
 
+/** \returns a random vector (not an expression, the vector is immediately evaluated).
+  *
+  * The parameter \a size is the size of the returned vector.
+  * Must be compatible with this MatrixBase type.
+  *
+  * \only_for_vectors
+  *
+  * This variant is meant to be used for dynamic-size vector types. For fixed-size types,
+  * it is redundant to pass \a size as argument, so random() should be used
+  * instead.
+  *
+  * Example: \include MatrixBase_random_int.cpp
+  * Output: \verbinclude MatrixBase_random_int.out
+  *
+  * \sa random(), random(int,int)
+  */
 template<typename Scalar, typename Derived>
 const Eval<Random<Derived> > MatrixBase<Scalar, Derived>::random(int size)
 {
@@ -73,6 +109,17 @@ const Eval<Random<Derived> > MatrixBase<Scalar, Derived>::random(int size)
   else return Random<Derived>(size, 1).eval();
 }
 
+/** \returns a fixed-size random matrix or vector
+  * (not an expression, the matrix is immediately evaluated).
+  *
+  * This variant is only for fixed-size MatrixBase types. For dynamic-size types, you
+  * need to use the variants taking size arguments.
+  *
+  * Example: \include MatrixBase_random.cpp
+  * Output: \verbinclude MatrixBase_random.out
+  *
+  * \sa random(int), random(int,int)
+  */
 template<typename Scalar, typename Derived>
 const Eval<Random<Derived> > MatrixBase<Scalar, Derived>::random()
 {

Eigen/src/Core/Zero.h

@@ -26,6 +26,12 @@
 #ifndef EIGEN_ZERO_H
 #define EIGEN_ZERO_H
 
+/** \class Zero
+  *
+  * \brief Expression of a zero matrix or vector.
+  *
+  * \sa MatrixBase::zero(), MatrixBase::zero(int), MatrixBase::zero(int,int)
+  */
 template<typename MatrixType> class Zero : NoOperatorEquals,
   public MatrixBase<typename MatrixType::Scalar, Zero<MatrixType> >
 {
@@ -59,12 +65,42 @@ template<typename MatrixType> class Zero : NoOperatorEquals,
     int m_rows, m_cols;
 };
 
+/** \returns an expression of a zero matrix.
+  *
+  * The parameters \a rows and \a cols are the number of rows and of columns of
+  * the returned matrix. Must be compatible with this MatrixBase type.
+  *
+  * This variant is meant to be used for dynamic-size matrix types. For fixed-size types,
+  * it is redundant to pass \a rows and \a cols as arguments, so zero() should be used
+  * instead.
+  *
+  * Example: \include MatrixBase_zero_int_int.cpp
+  * Output: \verbinclude MatrixBase_zero_int_int.out
+  *
+  * \sa zero(), zero(int)
+  */
 template<typename Scalar, typename Derived>
 const Zero<Derived> MatrixBase<Scalar, Derived>::zero(int rows, int cols)
 {
   return Zero<Derived>(rows, cols);
 }
 
+/** \returns an expression of a zero vector.
+  *
+  * The parameter \a size is the size of the returned vector.
+  * Must be compatible with this MatrixBase type.
+  *
+  * \only_for_vectors
+  *
+  * This variant is meant to be used for dynamic-size vector types. For fixed-size types,
+  * it is redundant to pass \a size as argument, so zero() should be used
+  * instead.
+  *
+  * Example: \include MatrixBase_zero_int.cpp
+  * Output: \verbinclude MatrixBase_zero_int.out
+  *
+  * \sa zero(), zero(int,int)
+  */
 template<typename Scalar, typename Derived>
 const Zero<Derived> MatrixBase<Scalar, Derived>::zero(int size)
 {
@@ -73,6 +109,16 @@ const Zero<Derived> MatrixBase<Scalar, Derived>::zero(int size)
   else return Zero<Derived>(size, 1);
 }
 
+/** \returns an expression of a fixed-size zero matrix or vector.
+  *
+  * This variant is only for fixed-size MatrixBase types. For dynamic-size types, you
+  * need to use the variants taking size arguments.
+  *
+  * Example: \include MatrixBase_zero.cpp
+  * Output: \verbinclude MatrixBase_zero.out
+  *
+  * \sa zero(int), zero(int,int)
+  */
 template<typename Scalar, typename Derived>
 const Zero<Derived> MatrixBase<Scalar, Derived>::zero()
 {

doc/snippets/MatrixBase_map.cpp

@@ -0,0 +1,5 @@
+int data[4] = {1,3,0,2};
+cout << Matrix2i::map(data) << endl;
+Matrix2i::map(data) *= 2;
+cout << "The data is now:" << endl;
+for(int i = 0; i < 4; i++) cout << data[i] << endl;

doc/snippets/MatrixBase_map_int.cpp

@@ -0,0 +1,5 @@
+int data[4] = {1,3,0,2};
+cout << VectorXi::map(data, 4) << endl;
+VectorXi::map(data, 4) *= 2;
+cout << "The data is now:" << endl;
+for(int i = 0; i < 4; i++) cout << data[i] << endl;

doc/snippets/MatrixBase_map_int_int.cpp

@@ -0,0 +1,5 @@
+int data[4] = {1,3,0,2};
+cout << MatrixXi::map(data, 2, 2) << endl;
+MatrixXi::map(data, 2, 2) *= 2;
+cout << "The data is now:" << endl;
+for(int i = 0; i < 4; i++) cout << data[i] << endl;

doc/snippets/MatrixBase_ones.cpp

@@ -0,0 +1,2 @@
+cout << Matrix2d::ones() << endl;
+cout << 6 * RowVector4i::ones() << endl;

doc/snippets/MatrixBase_ones_int.cpp

@@ -0,0 +1,2 @@
+cout << 6 * RowVectorXi::ones(4) << endl;
+cout << VectorXf::ones(2) << endl;

doc/snippets/MatrixBase_ones_int_int.cpp

@@ -0,0 +1 @@
+cout << MatrixXi::ones(2,3) << endl;

doc/snippets/MatrixBase_random.cpp

@@ -0,0 +1 @@
+cout << 100 * Matrix2i::random() << endl;

doc/snippets/MatrixBase_random_int.cpp

@@ -0,0 +1 @@
+cout << VectorXi::random(2) << endl;

doc/snippets/MatrixBase_random_int_int.cpp

@@ -0,0 +1 @@
+cout << MatrixXi::random(2,3) << endl;

doc/snippets/MatrixBase_transpose.cpp

@@ -1,4 +1,4 @@
-Matrix2f m = Matrix2f::random();
+Matrix2i m = Matrix2i::random();
 cout << "Here is the matrix m:" << endl << m << endl;
 cout << "Here is the transpose of m:" << endl << m.transpose() << endl;
 cout << "Here is the coefficient (1,0) in the transpose of m:" << endl

doc/snippets/MatrixBase_zero.cpp

@@ -0,0 +1,2 @@
+cout << Matrix2d::zero() << endl;
+cout << RowVector4i::zero() << endl;

doc/snippets/MatrixBase_zero_int.cpp

@@ -0,0 +1,2 @@
+cout << RowVectorXi::zero(4) << endl;
+cout << VectorXf::zero(2) << endl;

doc/snippets/MatrixBase_zero_int_int.cpp

@@ -0,0 +1 @@
+cout << MatrixXi::zero(2,3) << endl;