add internal documentation

5 files changed, 54 insertions, 12 deletions

diff --git a/Eigen/src/Core/Dot.h b/Eigen/src/Core/Dot.h
index 63441eeed..3032f79ec 100644
--- a/Eigen/src/Core/Dot.h
+++ b/Eigen/src/Core/Dot.h
@@ -273,7 +273,7 @@ MatrixBase<Derived>::dot(const MatrixBase<OtherDerived>& other) const
 
 /** \returns the squared norm of *this, i.e. the dot product of *this with itself.
   *
-  * \note This is \em not the \em l2 norm.
+  * \note This is \em not the \em l2 norm, but its square.
   *
   * \deprecated Use squaredNorm() instead. This norm2() function is kept only for compatibility and will be removed in Eigen 2.0.
   *
@@ -282,7 +282,7 @@ MatrixBase<Derived>::dot(const MatrixBase<OtherDerived>& other) const
   * \sa dot(), norm()
   */
 template<typename Derived>
-inline typename NumTraits<typename ei_traits<Derived>::Scalar>::Real MatrixBase<Derived>::norm2() const
+EIGEN_DEPRECATED inline typename NumTraits<typename ei_traits<Derived>::Scalar>::Real MatrixBase<Derived>::norm2() const
 {
   return ei_real(dot(*this));
 }
diff --git a/Eigen/src/Core/Matrix.h b/Eigen/src/Core/Matrix.h
index b7cc603f4..86205aab2 100644
--- a/Eigen/src/Core/Matrix.h
+++ b/Eigen/src/Core/Matrix.h
@@ -44,11 +44,11 @@
   *
   * \note <b>Fixed-size versus dynamic-size:</b>
   * Fixed-size means that the numbers of rows and columns are known are compile-time. In this case, Eigen allocates the array
-  * of coefficients as a fixed-size array on the stack. This makes sense for very small matrices, typically up to 4x4, sometimes up
+  * of coefficients as a fixed-size array, as a class member. This makes sense for very small matrices, typically up to 4x4, sometimes up
   * to 16x16. Larger matrices should be declared as dynamic-size even if one happens to know their size at compile-time.
   *
   * Dynamic-size means that the numbers of rows or columns are not necessarily known at compile-time. In this case they are runtime variables,
-  * and the array of coefficients is allocated dynamically, typically on the heap (See note on heap allocation below).
+  * and the array of coefficients is allocated dynamically, typically on the heap (See note on Usage of alloca() below).
   *
   * Note that dense matrices, be they Fixed-size or Dynamic-size, <em>do not</em> expand dynamically in the sense of a std::map.
   * If you want this behavior, see the Sparse module.
@@ -60,7 +60,7 @@
   * exceed a certain value. This happens when taking dynamic-size blocks inside fixed-size matrices: in this case _MaxRows and _MaxCols
   * are the dimensions of the original matrix, while _Rows and _Cols are Dynamic.
   *
-  * \note <b> Heap allocation:</b>
+  * \note <b> Usage of alloca():</b>
   * On the Linux platform, for small enough arrays, Eigen will avoid heap allocation and instead will use alloca() to perform a dynamic
   * allocation on the stack.
   *
@@ -85,7 +85,6 @@
   * v[1] = 0.2;
   * v(0) = 0.1;
   * v(1) = 0.2;
-
   *
   * Eigen::MatrixXi m(10, 10);
   * m(0, 1) = 1;
diff --git a/Eigen/src/Core/util/Constants.h b/Eigen/src/Core/util/Constants.h
index 89f671d1d..e83c9f74c 100644
--- a/Eigen/src/Core/util/Constants.h
+++ b/Eigen/src/Core/util/Constants.h
@@ -26,7 +26,25 @@
 #ifndef EIGEN_CONSTANTS_H
 #define EIGEN_CONSTANTS_H
 
+/** This value means that a quantity is not known at compile-time, and that instead the value is
+  * stored in some runtime variable.
+  *
+  * Explanation for the choice of this value:
+  * - It should be positive and larger than any reasonable compile-time-fixed number of rows or columns.
+  *   This means that it should be at least 128 or so.
+  * - It should be smaller than the sqrt of INT_MAX. Indeed, we often multiply a number of rows with a number
+  *   of columns in order to compute a number of coefficients. Even if we guard that with an "if" checking whether
+  *   the values are Dynamic, we still get a compiler warning "integer overflow". So the only way to get around
+  *   it would be a meta-selector. Doing this everywhere would reduce code readability and lenghten compilation times.
+  *   Also, disabling compiler warnings for integer overflow, sounds like a bad idea.
+  *
+  * If you wish to port Eigen to a platform where sizeof(int)==2, it is perfectly possible to set Dynamic to, say, 250.
+  */
 const int Dynamic = 10000;
+
+/** This value means +Infinity; it is currently used only as the p parameter to MatrixBase::lpNorm<int>().
+  * The value Infinity there means the L-infinity norm.
+  */
 const int Infinity = -1;
 
 /** \defgroup flags flags
@@ -199,9 +217,9 @@ enum {
 };
 
 enum {
-  CompleteUnrolling,
+  NoUnrolling,
   InnerUnrolling,
-  NoUnrolling
+  CompleteUnrolling
 };
 
 enum {
@@ -211,9 +229,9 @@ enum {
 
 enum {
   IsDense         = 0,
+  IsSparse        = SparseBit,
   NoDirectAccess  = 0,
-  HasDirectAccess = DirectAccessBit,
-  IsSparse        = SparseBit
+  HasDirectAccess = DirectAccessBit
 };
 
 const int FullyCoherentAccessPattern  = 0x1;
diff --git a/Eigen/src/Core/util/Macros.h b/Eigen/src/Core/util/Macros.h
index c10c1bf8e..d557e808b 100644
--- a/Eigen/src/Core/util/Macros.h
+++ b/Eigen/src/Core/util/Macros.h
@@ -28,7 +28,10 @@
 
 #undef minor
 
-/** \internal  Defines the maximal loop size to enable meta unrolling of loops */
+/** \internal  Defines the maximal loop size to enable meta unrolling of loops.
+  *            Note that the value here is expressed in Eigen's own notion of "number of FLOPS",
+  *            it does not correspond to the number of iterations or the number of instructions
+  */
 #ifndef EIGEN_UNROLLING_LIMIT
 #define EIGEN_UNROLLING_LIMIT 100
 #endif
@@ -36,7 +39,7 @@
 /** \internal Define the maximal size in Bytes of L2 blocks.
   * The current value is set to generate blocks of 256x256 for float */
 #ifndef EIGEN_TUNE_FOR_L2_CACHE_SIZE
-#define EIGEN_TUNE_FOR_L2_CACHE_SIZE (1024*256)
+#define EIGEN_TUNE_FOR_L2_CACHE_SIZE (sizeof(float)*256*256)
 #endif
 
 #define USING_PART_OF_NAMESPACE_EIGEN \
diff --git a/Eigen/src/Core/util/XprHelper.h b/Eigen/src/Core/util/XprHelper.h
index 05d50ce21..67d1f8c1b 100644
--- a/Eigen/src/Core/util/XprHelper.h
+++ b/Eigen/src/Core/util/XprHelper.h
@@ -41,6 +41,10 @@ class ei_no_assignment_operator
     ei_no_assignment_operator& operator=(const ei_no_assignment_operator&);
 };
 
+/** \internal If the template parameter Value is Dynamic, this class is just a wrapper around an int variable that
+  * can be accessed using value() and setValue().
+  * Otherwise, this class is an empty structure and value() just returns the template parameter Value.
+  */
 template<int Value> class ei_int_if_dynamic EIGEN_EMPTY_STRUCT
 {
   public:
@@ -136,6 +140,24 @@ template<typename T> struct ei_eval_to_column_major
 template<typename T> struct ei_must_nest_by_value { enum { ret = false }; };
 template<typename T> struct ei_must_nest_by_value<NestByValue<T> > { enum { ret = true }; };
 
+/** \internal Determines how a given expression should be nested into another one.
+  * For example, when you do a * (b+c), Eigen will determine how the expression b+c should be
+  * nested into the bigger product expression. The choice is between nesting the expression b+c as-is, or
+  * evaluating that expression b+c into a temporary variable d, and nest d so that the resulting expression is
+  * a*d. Evaluating can be beneficial for example if every coefficient access in the resulting expression causes
+  * many coefficient accesses in the nested expressions -- as is the case with matrix product for example.
+  *
+  * \param T the type of the expression being nested
+  * \param n the number of coefficient accesses in the nested expression for each coefficient access in the bigger expression.
+  *
+  * Example. Suppose that a, b, and c are of type Matrix3d. The user forms the expression a*(b+c).
+  * b+c is an expression "sum of matrices", which we will denote by S. In order to determine how to nest it,
+  * the Product expression uses: ei_nested<S, 3>::ret, which turns out to be Matrix3d because the internal logic of
+  * ei_nested determined that in this case it was better to evaluate the expression b+c into a temporary. On the other hand,
+  * since a is of type Matrix3d, the Product expression nests it as ei_nested<Matrix3d, 3>::ret, which turns out to be
+  * const Matrix3d&, because the internal logic of ei_nested determined that since a was already a matrix, there was no point
+  * in copying it into another matrix.
+  */
 template<typename T, int n=1, typename EvalType = typename ei_eval<T>::type> struct ei_nested
 {
   enum {