big changes in Doxygen configuration; work around bug with doxygen parsing of

initialized enum values showing the last word the initializer instead of the actual
enum value's name; add some more docs.

9 files changed, 157 insertions, 114 deletions

diff --git a/Eigen/src/Array/AllAndAny.h b/Eigen/src/Array/AllAndAny.h
index 74fbf38c9..4da017c6e 100644
--- a/Eigen/src/Array/AllAndAny.h
+++ b/Eigen/src/Array/AllAndAny.h
@@ -77,7 +77,9 @@ struct ei_any_unroller<Derived, Dynamic>
   inline static bool run(const Derived &) { return false; }
 };
 
-/** \returns true if all coefficients are true
+/** \array_module
+  * 
+  * \returns true if all coefficients are true
   *
   * \sa MatrixBase::any()
   */
@@ -99,7 +101,9 @@ bool MatrixBase<Derived>::all(void) const
   }
 }
 
-/** \returns true if at least one coefficient is true
+/** \array_module
+  * 
+  * \returns true if at least one coefficient is true
   *
   * \sa MatrixBase::any()
   */
diff --git a/Eigen/src/Array/CwiseOperators.h b/Eigen/src/Array/CwiseOperators.h
index f9f9e1267..d1f34b0e3 100644
--- a/Eigen/src/Array/CwiseOperators.h
+++ b/Eigen/src/Array/CwiseOperators.h
@@ -27,7 +27,9 @@
 
 // -- unary operators --
 
-/** \returns an expression of the coefficient-wise square root of *this. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise square root of *this. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_sqrt_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwiseSqrt() const
@@ -35,7 +37,9 @@ MatrixBase<Derived>::cwiseSqrt() const
   return derived();
 }
 
-/** \returns an expression of the coefficient-wise exponential of *this. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise exponential of *this. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_exp_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwiseExp() const
@@ -43,7 +47,9 @@ MatrixBase<Derived>::cwiseExp() const
   return derived();
 }
 
-/** \returns an expression of the coefficient-wise logarithm of *this. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise logarithm of *this. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_log_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwiseLog() const
@@ -51,7 +57,9 @@ MatrixBase<Derived>::cwiseLog() const
   return derived();
 }
 
-/** \returns an expression of the coefficient-wise cosine of *this. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise cosine of *this. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_cos_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwiseCos() const
@@ -59,7 +67,9 @@ MatrixBase<Derived>::cwiseCos() const
   return derived();
 }
 
-/** \returns an expression of the coefficient-wise sine of *this. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise sine of *this. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_sin_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwiseSin() const
@@ -67,7 +77,9 @@ MatrixBase<Derived>::cwiseSin() const
   return derived();
 }
 
-/** \returns an expression of the coefficient-wise power of *this to the given exponent. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise power of *this to the given exponent. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_pow_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwisePow(const Scalar& exponent) const
@@ -76,7 +88,9 @@ MatrixBase<Derived>::cwisePow(const Scalar& exponent) const
     (derived(), ei_scalar_pow_op<Scalar>(exponent));
 }
 
-/** \returns an expression of the coefficient-wise reciprocal of *this. */
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise reciprocal of *this. */
 template<typename Derived>
 inline const CwiseUnaryOp<ei_scalar_inverse_op<typename ei_traits<Derived>::Scalar>, Derived>
 MatrixBase<Derived>::cwiseInverse() const
@@ -86,7 +100,9 @@ MatrixBase<Derived>::cwiseInverse() const
 
 // -- binary operators --
 
-/** \returns an expression of the coefficient-wise \< operator of *this and \a other
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise \< operator of *this and \a other
   *
   * \sa class CwiseBinaryOp
   */
@@ -98,7 +114,9 @@ MatrixBase<Derived>::cwiseLessThan(const MatrixBase<OtherDerived> &other) const
   return cwise(other, std::less<Scalar>());
 }
 
-/** \returns an expression of the coefficient-wise \<= operator of *this and \a other
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise \<= operator of *this and \a other
   *
   * \sa class CwiseBinaryOp
   */
@@ -110,7 +128,9 @@ MatrixBase<Derived>::cwiseLessEqual(const MatrixBase<OtherDerived> &other) const
   return cwise(other, std::less_equal<Scalar>());
 }
 
-/** \returns an expression of the coefficient-wise \> operator of *this and \a other
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise \> operator of *this and \a other
   *
   * \sa class CwiseBinaryOp
   */
@@ -122,7 +142,9 @@ MatrixBase<Derived>::cwiseGreaterThan(const MatrixBase<OtherDerived> &other) con
   return cwise(other, std::greater<Scalar>());
 }
 
-/** \returns an expression of the coefficient-wise \>= operator of *this and \a other
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise \>= operator of *this and \a other
   *
   * \sa class CwiseBinaryOp
   */
@@ -134,7 +156,9 @@ MatrixBase<Derived>::cwiseGreaterEqual(const MatrixBase<OtherDerived> &other) co
   return cwise(other, std::greater_equal<Scalar>());
 }
 
-/** \returns an expression of the coefficient-wise == operator of *this and \a other
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise == operator of *this and \a other
   *
   * \sa class CwiseBinaryOp
   */
@@ -146,7 +170,9 @@ MatrixBase<Derived>::cwiseEqualTo(const MatrixBase<OtherDerived> &other) const
   return cwise(other, std::equal_to<Scalar>());
 }
 
-/** \returns an expression of the coefficient-wise != operator of *this and \a other
+/** \array_module
+  * 
+  * \returns an expression of the coefficient-wise != operator of *this and \a other
   *
   * \sa class CwiseBinaryOp
   */
diff --git a/Eigen/src/Array/Functors.h b/Eigen/src/Array/Functors.h
index 3169106d8..3452ddc94 100644
--- a/Eigen/src/Array/Functors.h
+++ b/Eigen/src/Array/Functors.h
@@ -26,6 +26,9 @@
 #define EIGEN_ARRAY_FUNCTORS_H
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to compute the square root of a scalar
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwiseSqrt()
@@ -38,6 +41,9 @@ struct ei_functor_traits<ei_scalar_sqrt_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false }; };
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to compute the exponential of a scalar
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwiseExp()
@@ -50,6 +56,9 @@ struct ei_functor_traits<ei_scalar_exp_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false }; };
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to compute the logarithm of a scalar
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwiseLog()
@@ -62,6 +71,9 @@ struct ei_functor_traits<ei_scalar_log_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false }; };
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to compute the cosine of a scalar
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwiseCos()
@@ -74,6 +86,9 @@ struct ei_functor_traits<ei_scalar_cos_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false }; };
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to compute the sine of a scalar
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwiseSin()
@@ -86,6 +101,9 @@ struct ei_functor_traits<ei_scalar_sin_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false }; };
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to raise a scalar to a power
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwisePow
@@ -101,6 +119,9 @@ struct ei_functor_traits<ei_scalar_pow_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false }; };
 
 /** \internal
+  *
+  * \array_module
+  * 
   * \brief Template functor to compute the reciprocal of a scalar
   *
   * \sa class CwiseUnaryOp, MatrixBase::cwiseInverse
diff --git a/Eigen/src/Array/PartialRedux.h b/Eigen/src/Array/PartialRedux.h
index 6b33caaa9..aa85b6ac0 100644
--- a/Eigen/src/Array/PartialRedux.h
+++ b/Eigen/src/Array/PartialRedux.h
@@ -26,7 +26,9 @@
 #ifndef EIGEN_PARTIAL_REDUX_H
 #define EIGEN_PARTIAL_REDUX_H
 
-/** \class PartialRedux
+/** \array_module
+  * 
+  * \class PartialRedux
   *
   * \brief Generic expression of a partially reduxed matrix
   *
@@ -93,7 +95,9 @@ class PartialRedux : ei_no_assignment_operator,
     const BinaryOp m_functor;
 };
 
-/** \returns a row vector expression of *this vertically reduxed by \a func
+/** \array_module
+  * 
+  * \returns a row vector expression of *this vertically reduxed by \a func
   *
   * The template parameter \a BinaryOp is the type of the functor
   * of the custom redux operator. Note that func must be an associative operator.
@@ -108,7 +112,9 @@ MatrixBase<Derived>::verticalRedux(const BinaryOp& func) const
   return PartialRedux<Vertical, BinaryOp, Derived>(derived(), func);
 }
 
-/** \returns a row vector expression of *this horizontally reduxed by \a func
+/** \array_module
+  * 
+  * \returns a row vector expression of *this horizontally reduxed by \a func
   *
   * The template parameter \a BinaryOp is the type of the functor
   * of the custom redux operator. Note that func must be an associative operator.
diff --git a/Eigen/src/Array/Random.h b/Eigen/src/Array/Random.h
index 2e19e1ff0..5a0f0814b 100644
--- a/Eigen/src/Array/Random.h
+++ b/Eigen/src/Array/Random.h
@@ -33,7 +33,9 @@ template<typename Scalar>
 struct ei_functor_traits<ei_scalar_random_op<Scalar> >
 { enum { Cost = 5 * NumTraits<Scalar>::MulCost, IsVectorizable = false, IsRepeatable = false }; };
 
-/** \returns a random matrix (not an expression, the matrix is immediately evaluated).
+/** \array_module
+  * 
+  * \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.
@@ -54,7 +56,9 @@ MatrixBase<Derived>::random(int rows, int cols)
   return create(rows, cols, ei_scalar_random_op<Scalar>());
 }
 
-/** \returns a random vector (not an expression, the vector is immediately evaluated).
+/** \array_module
+  * 
+  * \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.
@@ -77,7 +81,9 @@ MatrixBase<Derived>::random(int size)
   return create(size, ei_scalar_random_op<Scalar>());
 }
 
-/** \returns a fixed-size random matrix or vector
+/** \array_module
+  * 
+  * \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
@@ -95,7 +101,9 @@ MatrixBase<Derived>::random()
   return create(RowsAtCompileTime, ColsAtCompileTime, ei_scalar_random_op<Scalar>());
 }
 
-/** Sets all coefficients in this expression to random values.
+/** \array_module
+  * 
+  * Sets all coefficients in this expression to random values.
   *
   * Example: \include MatrixBase_setRandom.cpp
   * Output: \verbinclude MatrixBase_setRandom.out
diff --git a/Eigen/src/Core/MatrixBase.h b/Eigen/src/Core/MatrixBase.h
index e0220fd19..3b08ea7c6 100644
--- a/Eigen/src/Core/MatrixBase.h
+++ b/Eigen/src/Core/MatrixBase.h
@@ -55,33 +55,33 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
 
   public:
 
-    /// \name Compile-time traits
-    //@{
     typedef typename ei_traits<Derived>::Scalar Scalar;
-
     typedef typename ei_packet_traits<Scalar>::type PacketScalar;
 
     enum {
 
-      RowsAtCompileTime = ei_traits<Derived>::RowsAtCompileTime,
+      RowsAtCompileTime
         /**< The number of rows at compile-time. This is just a copy of the value provided
           * by the \a Derived type. If a value is not known at compile-time,
           * it is set to the \a Dynamic constant.
           * \sa MatrixBase::rows(), MatrixBase::cols(), ColsAtCompileTime, SizeAtCompileTime */
+        = ei_traits<Derived>::RowsAtCompileTime,
 
-     ColsAtCompileTime = ei_traits<Derived>::ColsAtCompileTime,
+     ColsAtCompileTime
         /**< The number of columns at compile-time. This is just a copy of the value provided
           * by the \a Derived type. If a value is not known at compile-time,
           * it is set to the \a Dynamic constant.
           * \sa MatrixBase::rows(), MatrixBase::cols(), RowsAtCompileTime, SizeAtCompileTime */
+        = ei_traits<Derived>::ColsAtCompileTime,
 
-      SizeAtCompileTime = ei_size_at_compile_time<ei_traits<Derived>::RowsAtCompileTime,
-                                                  ei_traits<Derived>::ColsAtCompileTime>::ret,
+      SizeAtCompileTime
         /**< This is equal to the number of coefficients, i.e. the number of
           * rows times the number of columns, or to \a Dynamic if this is not
           * known at compile-time. \sa RowsAtCompileTime, ColsAtCompileTime */
+        = ei_size_at_compile_time<ei_traits<Derived>::RowsAtCompileTime,
+                                  ei_traits<Derived>::ColsAtCompileTime>::ret,
 
-      MaxRowsAtCompileTime = ei_traits<Derived>::MaxRowsAtCompileTime,
+      MaxRowsAtCompileTime
         /**< This value is equal to the maximum possible number of rows that this expression
           * might have. If this expression might have an arbitrarily high number of rows,
           * this value is set to \a Dynamic.
@@ -91,8 +91,9 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           *
           * \sa RowsAtCompileTime, MaxColsAtCompileTime, MaxSizeAtCompileTime
           */
+        = ei_traits<Derived>::MaxRowsAtCompileTime,
 
-      MaxColsAtCompileTime = ei_traits<Derived>::MaxColsAtCompileTime,
+      MaxColsAtCompileTime
         /**< This value is equal to the maximum possible number of columns that this expression
           * might have. If this expression might have an arbitrarily high number of columns,
           * this value is set to \a Dynamic.
@@ -102,9 +103,9 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           *
           * \sa ColsAtCompileTime, MaxRowsAtCompileTime, MaxSizeAtCompileTime
           */
+        = ei_traits<Derived>::MaxColsAtCompileTime,
 
-      MaxSizeAtCompileTime = ei_size_at_compile_time<ei_traits<Derived>::MaxRowsAtCompileTime,
-                                                     ei_traits<Derived>::MaxColsAtCompileTime>::ret,
+      MaxSizeAtCompileTime
         /**< This value is equal to the maximum possible number of coefficients that this expression
           * might have. If this expression might have an arbitrarily high number of coefficients,
           * this value is set to \a Dynamic.
@@ -114,26 +115,27 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
           *
           * \sa SizeAtCompileTime, MaxRowsAtCompileTime, MaxColsAtCompileTime
           */
+        = ei_size_at_compile_time<ei_traits<Derived>::MaxRowsAtCompileTime,
+                                                     ei_traits<Derived>::MaxColsAtCompileTime>::ret,
 
       IsVectorAtCompileTime
-        = ei_traits<Derived>::RowsAtCompileTime == 1 || ei_traits<Derived>::ColsAtCompileTime == 1,
         /**< This is set to true if either the number of rows or the number of
           * columns is known at compile-time to be equal to 1. Indeed, in that case,
           * we are dealing with a column-vector (if there is only one column) or with
           * a row-vector (if there is only one row). */
+        = ei_traits<Derived>::RowsAtCompileTime == 1 || ei_traits<Derived>::ColsAtCompileTime == 1,
 
-      Flags = ei_traits<Derived>::Flags,
+      Flags
         /**< This stores expression metadata which typically is inherited by new expressions
-          * constructed from this one. The available flags are:
-          * \li \c RowMajorBit: if this bit is set, the preferred storage order for an evaluation
-          *                  of this expression is row-major. Otherwise, it is column-major.
-          * \li \c LazyBit: if this bit is set, the next evaluation of this expression will be canceled.
-          *              This can be used, with care, to achieve lazy evaluation.
-          * \li \c LargeBit: if this bit is set, optimization will be tuned for large matrices (typically,
-          *               at least 32x32).
+          * constructed from this one. The available flags are FIXME!!! document that !!!
           */
+        = ei_traits<Derived>::Flags,
 
-      CoeffReadCost = ei_traits<Derived>::CoeffReadCost
+      CoeffReadCost
+        /**< This is a rough measure of how expensive it is to read one coefficient from
+          * this expression.
+          */
+        = ei_traits<Derived>::CoeffReadCost
     };
 
     /** Default constructor. Just checks at compile-time for self-consistency of the flags. */
@@ -152,10 +154,7 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
       * \sa class NumTraits
       */
     typedef typename NumTraits<Scalar>::Real RealScalar;
-    //@}
 
-    /// \name Run-time traits
-    //@{
     /** \returns the number of rows. \sa cols(), RowsAtCompileTime */
     inline int rows() const { return derived()._rows(); }
     /** \returns the number of columns. \sa row(), ColsAtCompileTime*/
@@ -168,10 +167,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
       * \code rows()==1 || cols()==1 \endcode
       * \sa rows(), cols(), IsVectorAtCompileTime. */
     inline bool isVector() const { return rows()==1 || cols()==1; }
-    //@}
 
-    /// \internal \name Default return types
-    //@{
+
     /** Represents a constant matrix */
     typedef CwiseNullaryOp<ei_scalar_constant_op<Scalar>,Derived> ConstantReturnType;
     /** Represents a vector block of a matrix  */
@@ -203,10 +200,7 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     typedef Transpose<NestByValue<typename ei_unref<ConjugateReturnType>::type> >
             AdjointReturnType;
     typedef Matrix<typename NumTraits<typename ei_traits<Derived>::Scalar>::Real, ei_traits<Derived>::ColsAtCompileTime, 1> EigenvaluesReturnType;
-    //@}
 
-    /// \name Copying and initialization
-    //@{
 
     /** Copies \a other into *this. \returns a reference to *this. */
     template<typename OtherDerived>
@@ -232,10 +226,7 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
 
     template<typename OtherDerived>
     CommaInitializer operator<< (const MatrixBase<OtherDerived>& other);
-    //@}
 
-    /// \name Coefficient accessors
-    //@{
     const Scalar coeff(int row, int col) const;
     const Scalar operator()(int row, int col) const;
 
@@ -261,12 +252,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     Scalar& y();
     Scalar& z();
     Scalar& w();
-    //@}
 
-    /** \name Linear structure
-      * sum, scalar multiple, ...
-      */
-    //@{
+
     const CwiseUnaryOp<ei_scalar_opposite_op<typename ei_traits<Derived>::Scalar>,Derived> operator-() const;
 
     template<typename OtherDerived>
@@ -295,12 +282,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     inline friend const CwiseUnaryOp<ei_scalar_multiple_op<typename ei_traits<Derived>::Scalar>, Derived>
     operator*(const Scalar& scalar, const MatrixBase& matrix)
     { return matrix*scalar; }
-    //@}
 
-    /** \name Matrix product
-      * and, as a special case, matrix-vector product
-      */
-    //@{
+
     template<typename OtherDerived>
     const typename ProductReturnType<OtherDerived>::Type
     operator*(const MatrixBase<OtherDerived> &other) const;
@@ -310,12 +293,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
 
     template<typename OtherDerived>
     typename OtherDerived::Eval inverseProduct(const MatrixBase<OtherDerived>& other) const;
-    //@}
 
-    /** \name Dot product and related notions
-      * including vector norm, adjoint, transpose ...
-      */
-    //@{
+
     template<typename OtherDerived>
     Scalar dot(const MatrixBase<OtherDerived>& other) const;
     RealScalar norm2() const;
@@ -325,10 +304,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     Transpose<Derived> transpose();
     const Transpose<Derived> transpose() const;
     const AdjointReturnType adjoint() const;
-    //@}
 
-    /// \name Sub-matrices
-    //@{
+
     Block<Derived, 1, ei_traits<Derived>::ColsAtCompileTime> row(int i);
     const Block<Derived, 1, ei_traits<Derived>::ColsAtCompileTime> row(int i) const;
 
@@ -377,10 +354,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
 
     template<unsigned int Mode> Part<Derived, Mode> part();
     template<unsigned int Mode> const Extract<Derived, Mode> extract() const;
-    //@}
 
-    /// \name Generating special matrices
-    //@{
+
     static const ConstantReturnType
     constant(int rows, int cols, const Scalar& value);
     static const ConstantReturnType
@@ -414,10 +389,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     Derived& setOnes();
     Derived& setRandom();
     Derived& setIdentity();
-    //@}
 
-    /// \name Comparison and diagnostic
-    //@{
+
     template<typename OtherDerived>
     bool isApprox(const MatrixBase<OtherDerived>& other,
                   RealScalar prec = precision<Scalar>()) const;
@@ -448,10 +421,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     template<typename OtherDerived>
     inline bool operator!=(const MatrixBase<OtherDerived>& other) const
     { return derived().cwiseNotEqualTo(other.derived()).all(); }
-    //@}
 
-    /// \name Special functions
-    //@{
+
     template<typename NewType>
     const CwiseUnaryOp<ei_scalar_cast_op<typename ei_traits<Derived>::Scalar, NewType>, Derived> cast() const;
 
@@ -475,10 +446,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     inline int stride(void) const { return derived()._stride(); }
 
     inline const NestByValue<Derived> nestByValue() const;
-    //@}
 
-    /// \name Coefficient-wise operations
-    //@{
+
     const ConjugateReturnType conjugate() const;
     const RealReturnType real() const;
 
@@ -507,10 +476,8 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     template<typename CustomBinaryOp, typename OtherDerived>
     const CwiseBinaryOp<CustomBinaryOp, Derived, OtherDerived>
     cwise(const MatrixBase<OtherDerived> &other, const CustomBinaryOp& func = CustomBinaryOp()) const;
-    //@}
 
-    /// \name Redux and visitor
-    //@{
+
     Scalar sum() const;
     Scalar trace() const;
 
@@ -526,21 +493,16 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
 
     template<typename Visitor>
     void visit(Visitor& func) const;
-    //@}
 
-    /// \name Casting to the derived type
-    //@{
+
     inline const Derived& derived() const { return *static_cast<const Derived*>(this); }
     inline Derived& derived() { return *static_cast<Derived*>(this); }
     inline Derived& const_cast_derived() const
     { return *static_cast<Derived*>(const_cast<MatrixBase*>(this)); }
-    //@}
 
-    /** \name Array module
-      *
-      * \code #include <Eigen/Array> \endcode
-      */
-    //@{
+
+/////////// Array module ///////////
+
     const CwiseUnaryOp<ei_scalar_sqrt_op<typename ei_traits<Derived>::Scalar>, Derived> cwiseSqrt() const;
     const CwiseUnaryOp<ei_scalar_exp_op<typename ei_traits<Derived>::Scalar>, Derived> cwiseExp() const;
     const CwiseUnaryOp<ei_scalar_log_op<typename ei_traits<Derived>::Scalar>, Derived> cwiseLog() const;
@@ -588,28 +550,21 @@ template<typename Derived> class MatrixBase : public ArrayBase<Derived>
     static const CwiseNullaryOp<ei_scalar_random_op<Scalar>,Derived> random(int rows, int cols);
     static const CwiseNullaryOp<ei_scalar_random_op<Scalar>,Derived> random(int size);
     static const CwiseNullaryOp<ei_scalar_random_op<Scalar>,Derived> random();
-    //@}
 
-    /** \name LU module
-      *
-      * \code #include <Eigen/LU> \endcode
-      */
-    //@{
+
+/////////// LU module ///////////
+
     const Inverse<typename ei_eval<Derived>::type, true> inverse() const;
     const Inverse<typename ei_eval<Derived>::type, false> quickInverse() const;
     Scalar determinant() const;
-    //@}
 
-    /** \name QR module
-      *
-      * \code #include <Eigen/QR> \endcode
-      */
-    //@{
+
+/////////// QR module ///////////
+
     const QR<typename ei_eval<Derived>::type> qr() const;
     
     EigenvaluesReturnType eigenvalues() const;
     RealScalar matrixNorm() const;
-    //@}
 
 };
 
diff --git a/Eigen/src/LU/Determinant.h b/Eigen/src/LU/Determinant.h
index e6a934147..fdb1673d8 100644
--- a/Eigen/src/LU/Determinant.h
+++ b/Eigen/src/LU/Determinant.h
@@ -67,6 +67,10 @@ const typename Derived::Scalar ei_bruteforce_det(const MatrixBase<Derived>& m)
   }
 }
 
+/** \lu_module
+  *
+  * \returns the determinant of this matrix
+  */
 template<typename Derived>
 typename ei_traits<Derived>::Scalar MatrixBase<Derived>::determinant() const
 {
diff --git a/Eigen/src/LU/Inverse.h b/Eigen/src/LU/Inverse.h
index 8ff723e05..e9830cbe1 100644
--- a/Eigen/src/LU/Inverse.h
+++ b/Eigen/src/LU/Inverse.h
@@ -25,7 +25,9 @@
 #ifndef EIGEN_INVERSE_H
 #define EIGEN_INVERSE_H
 
-/** \class Inverse
+/** \lu_module
+  *
+  * \class Inverse
   *
   * \brief Inverse of a matrix
   *
@@ -258,7 +260,9 @@ void Inverse<MatrixType, CheckExistence>::_compute(const MatrixType& matrix)
   else _compute_in_general_case(matrix);
 }
 
-/** \return the matrix inverse of \c *this, if it exists.
+/** \lu_module
+  *
+  * \returns the matrix inverse of \c *this, if it exists.
   *
   * Example: \include MatrixBase_inverse.cpp
   * Output: \verbinclude MatrixBase_inverse.out
@@ -272,7 +276,9 @@ MatrixBase<Derived>::inverse() const
   return Inverse<typename Derived::Eval, true>(eval());
 }
 
-/** \return the matrix inverse of \c *this, which is assumed to exist.
+/** \lu_module
+  *
+  * \returns the matrix inverse of \c *this, which is assumed to exist.
   *
   * Example: \include MatrixBase_quickInverse.cpp
   * Output: \verbinclude MatrixBase_quickInverse.out
diff --git a/Eigen/src/QR/SelfAdjointEigenSolver.h b/Eigen/src/QR/SelfAdjointEigenSolver.h
index 360acac36..0140de118 100644
--- a/Eigen/src/QR/SelfAdjointEigenSolver.h
+++ b/Eigen/src/QR/SelfAdjointEigenSolver.h
@@ -25,7 +25,9 @@
 #ifndef EIGEN_SELFADJOINTEIGENSOLVER_H
 #define EIGEN_SELFADJOINTEIGENSOLVER_H
 
-/** \class SelfAdjointEigenSolver
+/** \qr_module
+  *
+  * \class SelfAdjointEigenSolver
   *
   * \brief Eigen values/vectors solver for selfadjoint matrix
   *
@@ -91,6 +93,9 @@ static void ei_givens_rotation(Scalar a, Scalar b, Scalar& c, Scalar& s)
 }
 
 /** \internal
+  *
+  * \qr_module
+  *
   * Performs a QR step on a tridiagonal symmetric matrix represented as a
   * pair of two vectors \a diag and \a subdiag.
   *
@@ -161,6 +166,10 @@ void SelfAdjointEigenSolver<MatrixType>::compute(const MatrixType& matrix, bool
   }
 }
 
+/** \qr_module
+  *
+  * \returns a vector listing the eigenvalues of this matrix.
+  */
 template<typename Derived>
 inline Matrix<typename NumTraits<typename ei_traits<Derived>::Scalar>::Real, ei_traits<Derived>::ColsAtCompileTime, 1>
 MatrixBase<Derived>::eigenvalues() const
@@ -197,6 +206,10 @@ template<typename Derived> struct ei_matrixNorm_selector<Derived, false>
   }
 };
 
+/** \qr_module
+  *
+  * \returns the matrix norm of this matrix.
+  */
 template<typename Derived>
 inline typename NumTraits<typename ei_traits<Derived>::Scalar>::Real
 MatrixBase<Derived>::matrixNorm() const