many small fixes and documentation improvements,

this should be alpha5.

10 files changed, 90 insertions, 14 deletions

diff --git a/Eigen/src/Core/Block.h b/Eigen/src/Core/Block.h
index d5b1d9de1..65b9ad649 100644
--- a/Eigen/src/Core/Block.h
+++ b/Eigen/src/Core/Block.h
@@ -497,7 +497,7 @@ inline const Block<Derived, CRows, CCols> MatrixBase<Derived>
   * Example: \include MatrixBase_block_int_int.cpp
   * Output: \verbinclude MatrixBase_block_int_int.out
   *
-  * \note since block is a templated member, the keyword template as to be used
+  * \note since block is a templated member, the keyword template has to be used
   * if the matrix type is also a template parameter: \code m.template block<3,3>(1,1); \endcode
   *
   * \sa class Block, block(int,int,int,int)
diff --git a/Eigen/src/Core/CommaInitializer.h b/Eigen/src/Core/CommaInitializer.h
index d5e25b6e4..0a555e1b7 100644
--- a/Eigen/src/Core/CommaInitializer.h
+++ b/Eigen/src/Core/CommaInitializer.h
@@ -113,6 +113,7 @@ inline typename MatrixBase<Derived>::CommaInitializer MatrixBase<Derived>::opera
   return CommaInitializer(*static_cast<Derived*>(this), s);
 }
 
+/** \sa operator<<(const Scalar&) */
 template<typename Derived>
 template<typename OtherDerived>
 inline typename MatrixBase<Derived>::CommaInitializer
diff --git a/Eigen/src/Core/CwiseNullaryOp.h b/Eigen/src/Core/CwiseNullaryOp.h
index 66ccb40f1..009d89dec 100644
--- a/Eigen/src/Core/CwiseNullaryOp.h
+++ b/Eigen/src/Core/CwiseNullaryOp.h
@@ -218,7 +218,7 @@ MatrixBase<Derived>::constant(const Scalar& value)
 }
 
 template<typename Derived>
-bool MatrixBase<Derived>::isEqualToConstant
+bool MatrixBase<Derived>::isApproxToConstant
 (const Scalar& value, typename NumTraits<Scalar>::Real prec) const
 {
   for(int j = 0; j < cols(); j++)
@@ -408,7 +408,7 @@ template<typename Derived>
 bool MatrixBase<Derived>::isOnes
 (typename NumTraits<Scalar>::Real prec) const
 {
-  return isEqualToConstant(Scalar(1), prec);
+  return isApproxToConstant(Scalar(1), prec);
 }
 
 /** Sets all coefficients in this expression to one.
diff --git a/Eigen/src/Core/Extract.h b/Eigen/src/Core/Extract.h
index e9323733a..ea7240ada 100755
--- a/Eigen/src/Core/Extract.h
+++ b/Eigen/src/Core/Extract.h
@@ -93,7 +93,13 @@ template<typename MatrixType, unsigned int Mode> class Extract
 
 /** \returns an expression of a triangular matrix extracted from the current matrix
   *
-  * \sa part(), marked()
+  * The parameter \a Mode can have the following values: \c Upper, \c StrictlyUpper, \c UnitUpper,
+  * \c Lower, \c StrictlyLower, \c UnitLower.
+  *
+  * Example: \include MatrixBase_extract.cpp
+  * Output: \verbinclude MatrixBase_extract.out
+  *
+  * \sa class Extract, part(), marked()
   */
 template<typename Derived>
 template<unsigned int Mode>
diff --git a/Eigen/src/Core/Flagged.h b/Eigen/src/Core/Flagged.h
index 925066533..54a081f1e 100644
--- a/Eigen/src/Core/Flagged.h
+++ b/Eigen/src/Core/Flagged.h
@@ -101,6 +101,11 @@ template<typename ExpressionType, unsigned int Added, unsigned int Removed> clas
 };
 
 /** \returns an expression of *this with added flags
+  *
+  * Example: \include MatrixBase_marked.cpp
+  * Output: \verbinclude MatrixBase_marked.out
+  *
+  * \sa class Flagged, extract(), part()
   */
 template<typename Derived>
 template<unsigned int Added>
@@ -112,6 +117,11 @@ MatrixBase<Derived>::marked() const
 
 /** \returns an expression of *this with the following flags removed:
   * EvalBeforeNestingBit and EvalBeforeAssigningBit.
+  *
+  * Example: \include MatrixBase_lazy.cpp
+  * Output: \verbinclude MatrixBase_lazy.out
+  *
+  * \sa class Flagged, marked()
   */
 template<typename Derived>
 inline const Flagged<Derived, 0, EvalBeforeNestingBit | EvalBeforeAssigningBit>
diff --git a/Eigen/src/Core/InverseProduct.h b/Eigen/src/Core/InverseProduct.h
index 057590259..4a3579bbf 100755
--- a/Eigen/src/Core/InverseProduct.h
+++ b/Eigen/src/Core/InverseProduct.h
@@ -25,11 +25,19 @@
 #ifndef EIGEN_INVERSEPRODUCT_H
 #define EIGEN_INVERSEPRODUCT_H
 
-/** \returns the product of the inverse of *this with \a other.
+/** \returns the product of the inverse of \c *this with \a other.
   *
-  * This function computes the inverse-matrix matrix product inverse(*this) * \a other
-  * It works as a forward (resp. backward) substitution if *this is an upper (resp. lower)
+  * This function computes the inverse-matrix matrix product inverse(\c*this) * \a other
+  * It works as a forward (resp. backward) substitution if \c *this is an upper (resp. lower)
   * triangular matrix.
+  *
+  * It is required that \c *this be marked as either an upper or a lower triangular matrix, as
+  * can be done by marked(), and as is automatically the case with expressions such as those returned
+  * by extract().
+  * Example: \include MatrixBase_marked.cpp
+  * Output: \verbinclude MatrixBase_marked.out
+  *
+  * \sa marked(), extract()
   */
 template<typename Derived>
 template<typename OtherDerived>
diff --git a/Eigen/src/Core/MatrixBase.h b/Eigen/src/Core/MatrixBase.h
index 27d60d078..82d11f16e 100644
--- a/Eigen/src/Core/MatrixBase.h
+++ b/Eigen/src/Core/MatrixBase.h
@@ -136,10 +136,10 @@ template<typename Derived> class MatrixBase
       CoeffReadCost = ei_traits<Derived>::CoeffReadCost
     };
 
+    /** Default constructor. Just checks at compile-time for self-consistency of the flags. */
     MatrixBase()
     {
-      assert(!(  (Flags&UnitDiagBit && Flags&ZeroDiagBit)
-              || (Flags&UpperTriangularBit && Flags&LowerTriangularBit) ));
+      ei_assert(ei_are_flags_consistent<Flags>::ret);
     }
 
     /** This is the "real scalar" type; if the \a Scalar type is already real numbers
@@ -170,7 +170,7 @@ template<typename Derived> class MatrixBase
     inline bool isVector() const { return rows()==1 || cols()==1; }
     //@}
 
-    /// \name Default return types
+    /// \internal \name Default return types
     //@{
     /** Represents a constant matrix */
     typedef CwiseNullaryOp<ei_scalar_constant_op<Scalar>,Derived> ConstantReturnType;
@@ -289,7 +289,6 @@ template<typename Derived> class MatrixBase
 
     template<typename OtherDerived>
     typename OtherDerived::Eval inverseProduct(const MatrixBase<OtherDerived>& other) const;
-
     //@}
 
     /** \name Dot product and related notions
@@ -420,7 +419,7 @@ template<typename Derived> class MatrixBase
     bool isMuchSmallerThan(const MatrixBase<OtherDerived>& other,
                            RealScalar prec = precision<Scalar>()) const;
 
-    bool isEqualToConstant(const Scalar& value, RealScalar prec = precision<Scalar>()) const;
+    bool isApproxToConstant(const Scalar& value, RealScalar prec = precision<Scalar>()) const;
     bool isZero(RealScalar prec = precision<Scalar>()) const;
     bool isOnes(RealScalar prec = precision<Scalar>()) const;
     bool isIdentity(RealScalar prec = precision<Scalar>()) const;
diff --git a/Eigen/src/Core/Part.h b/Eigen/src/Core/Part.h
index 74c29f203..647e6cf2d 100644
--- a/Eigen/src/Core/Part.h
+++ b/Eigen/src/Core/Part.h
@@ -26,21 +26,44 @@
 #ifndef EIGEN_PART_H
 #define EIGEN_PART_H
 
+/** \class Part
+  *
+  * \brief Pseudo-expression allowing to write to a special part of a matrix
+  *
+  * This lvalue-only pseudo-expression allows to perform special operations
+  * on a matrix, such as writing only to the upper (above diagonal) part.
+  *
+  * It is the return type of MatrixBase::part() and most of the time this is
+  * the only way that it is used.
+  *
+  * \sa class Extract, MatrixBase::part()
+  */
 template<typename MatrixType, unsigned int Mode>
 class Part
 {
   public:
-    Part(MatrixType& matrix) : m_matrix(matrix) {}
+    Part(MatrixType& matrix);
+    /** \sa operator=(), MatrixBase::lazyAssign() */
     template<typename Other> void lazyAssign(const Other& other);
+    /** \sa MatrixBase::operator=() */
     template<typename Other> void operator=(const Other& other);
+    /** \sa MatrixBase::operator+=() */
     template<typename Other> void operator+=(const Other& other);
+    /** \sa MatrixBase::operator-=() */
     template<typename Other> void operator-=(const Other& other);
+    /** \sa MatrixBase::operator*=() */
     void operator*=(const typename ei_traits<MatrixType>::Scalar& other);
+    /** \sa MatrixBase::operator/=() */
     void operator/=(const typename ei_traits<MatrixType>::Scalar& other);
+    /** \sa MatrixBase::setConstant() */
     void setConstant(const typename ei_traits<MatrixType>::Scalar& value);
+    /** \sa MatrixBase::setZero() */
     void setZero();
+    /** \sa MatrixBase::setOnes() */
     void setOnes();
+    /** \sa MatrixBase::setRandom() */
     void setRandom();
+    /** \sa MatrixBase::setIdentity() */
     void setIdentity();
 
   private:
@@ -48,11 +71,22 @@ class Part
 };
 
 template<typename MatrixType, unsigned int Mode>
+inline Part<MatrixType, Mode>::Part(MatrixType& matrix)
+ : m_matrix(matrix)
+{
+  ei_assert(ei_are_flags_consistent<Mode>::ret);
+}
+
+template<typename MatrixType, unsigned int Mode>
 template<typename Other>
 inline void Part<MatrixType, Mode>::operator=(const Other& other)
 {
   if(Other::Flags & EvalBeforeAssigningBit)
-    lazyAssign(other.eval());
+  {
+    typename ei_eval<Other>::type other_evaluated(other.rows(), other.cols());
+    other_evaluated.template part<Mode>().lazyAssign(other);
+    lazyAssign(other_evaluated);
+  }
   else
     lazyAssign(other.derived());
 }
@@ -210,6 +244,16 @@ inline void Part<MatrixType, Mode>::setRandom()
   *this = MatrixType::random(m_matrix.rows(), m_matrix.cols());
 }
 
+/** \returns a lvalue pseudo-expression allowing to perform special operations on \c *this.
+  *
+  * The \a Mode parameter can have the following values: \c Upper, \c StrictlyUpper, \c Lower,
+  * \c StrictlyLower, \c SelfAdjoint.
+  *
+  * Example: \include MatrixBase_part.cpp
+  * Output: \verbinclude MatrixBase_part.out
+  *
+  * \sa class Part, MatrixBase::extract(), MatrixBase::marked()
+  */
 template<typename Derived>
 template<unsigned int Mode>
 inline Part<Derived, Mode> MatrixBase<Derived>::part()
diff --git a/Eigen/src/Core/util/Macros.h b/Eigen/src/Core/util/Macros.h
index a31e73bb9..717e3e072 100644
--- a/Eigen/src/Core/util/Macros.h
+++ b/Eigen/src/Core/util/Macros.h
@@ -135,6 +135,7 @@ typedef typename Eigen::NumTraits<Scalar>::Real RealScalar; \
 typedef typename Base::PacketScalar PacketScalar; \
 typedef typename Eigen::ei_nested<Derived>::type Nested; \
 typedef typename Eigen::ei_eval<Derived>::type Eval; \
+typedef typename Eigen::Inverse<Eval> InverseType; \
 enum { RowsAtCompileTime = Base::RowsAtCompileTime, \
        ColsAtCompileTime = Base::ColsAtCompileTime, \
        MaxRowsAtCompileTime = Base::MaxRowsAtCompileTime, \
diff --git a/Eigen/src/Core/util/Meta.h b/Eigen/src/Core/util/Meta.h
index f1edf7d6f..792f65b33 100644
--- a/Eigen/src/Core/util/Meta.h
+++ b/Eigen/src/Core/util/Meta.h
@@ -210,4 +210,11 @@ template<typename T, int n=1> struct ei_nested
   >::ret type;
 };
 
+template<unsigned int Flags> struct ei_are_flags_consistent
+{
+  enum { ret = !( (Flags&UnitDiagBit && Flags&ZeroDiagBit)
+                  || (Flags&UpperTriangularBit && Flags&LowerTriangularBit) )
+  };
+};
+
 #endif // EIGEN_META_H