document LvalueBit better

2 files changed, 26 insertions, 15 deletions

diff --git a/Eigen/src/Core/DenseCoeffsBase.h b/Eigen/src/Core/DenseCoeffsBase.h
index 9de9ae280..b4dbe1d95 100644
--- a/Eigen/src/Core/DenseCoeffsBase.h
+++ b/Eigen/src/Core/DenseCoeffsBase.h
@@ -44,6 +44,11 @@ class DenseCoeffsBase<Derived,ReadOnlyAccessors> : public EigenBase<Derived>
     typedef typename internal::traits<Derived>::Index Index;
     typedef typename internal::traits<Derived>::Scalar Scalar;
     typedef typename internal::packet_traits<Scalar>::type PacketScalar;
+
+    // explanation for this CoeffReturnType typedef.
+    // this is the return type of the coeff() method.
+    // The LvalueBit means exactly that we can offer a coeffRef() method, which means exactly that we can get references
+    // to coeffs, which means exactly that we can have coeff() return a const reference (as opposed to returning a value).
     typedef typename internal::conditional<bool(internal::traits<Derived>::Flags&LvalueBit),
                                 const Scalar&,
                                 typename internal::conditional<internal::is_arithmetic<Scalar>::value, Scalar, const Scalar>::type
@@ -230,7 +235,7 @@ class DenseCoeffsBase<Derived,ReadOnlyAccessors> : public EigenBase<Derived>
 
   protected:
     // explanation: DenseBase is doing "using ..." on the methods from DenseCoeffsBase.
-    // But some methods are only available in the EnableDirectAccessAPI case.
+    // But some methods are only available in the DirectAccess case.
     // So we add dummy methods here with these names, so that "using... " doesn't fail.
     // It's not private so that the child class DenseBase can access them, and it's not public
     // either since it's an implementation detail, so has to be protected.
diff --git a/Eigen/src/Core/util/Constants.h b/Eigen/src/Core/util/Constants.h
index 60da5c76a..99b4f3319 100644
--- a/Eigen/src/Core/util/Constants.h
+++ b/Eigen/src/Core/util/Constants.h
@@ -125,27 +125,33 @@ const unsigned int LinearAccessBit = 0x10;
 
 /** \ingroup flags
   *
-  * Means that the underlying array of coefficients can be directly accessed. This means two things.
-  * First, references to the coefficients must be available through coeffRef(int, int). This rules out read-only
-  * expressions whose coefficients are computed on demand by coeff(int, int). Second, the memory layout of the
-  * array of coefficients must be exactly the natural one suggested by rows(), cols(), outerStride(), innerStride(), and the RowMajorBit.
-  * This rules out expressions such as Diagonal, whose coefficients, though referencable, do not have
-  * such a regular memory layout.
+  * Means the expression has a coeffRef() method, i.e. is writable as its individual coefficients are directly addressable.
+  * This rules out read-only expressions.
+  *
+  * Note that DirectAccessBit implies LvalueBit, but the converse is false: LvalueBit doesn't imply DirectAccessBit because
+  * DirectAccessBit means that the whole memory layout is a plain strided array.
+  *
+  * Expressions having LvalueBit also have their coeff() method returning a const reference instead of returning a new value.
   */
-const unsigned int DirectAccessBit = 0x20;
+const unsigned int LvalueBit = 0x20;
 
 /** \ingroup flags
   *
-  * means the first coefficient packet is guaranteed to be aligned */
-const unsigned int AlignedBit = 0x40;
+  * Means that the underlying array of coefficients can be directly accessed. This means two things.
+  * 
+  * First, this means LvalueBit, i.e. this means that the expression has a coeffRef() method, i.e. is writable as its
+  * individual coefficients are directly addressable. This rules out read-only expressions.
+  *
+  * Second, the memory layout of the array of coefficients must be exactly the natural one suggested by rows(), cols(),
+  * outerStride(), innerStride(), and the RowMajorBit. This rules out expressions such as Diagonal, whose coefficients,
+  * though referencable, do not have such a regular memory layout.
+  */
+const unsigned int DirectAccessBit = 0x40;
 
 /** \ingroup flags
   *
-  * Means the expression is writable. Note that DirectAccessBit implies LvalueBit.
-  * Internaly, it is mainly used to enable the writable coeff accessors, and makes
-  * the read-only coeff accessors to return by const reference.
-  */
-const unsigned int LvalueBit = 0x80;
+  * means the first coefficient packet is guaranteed to be aligned */
+const unsigned int AlignedBit = 0x80;
 
 const unsigned int NestByRefBit = 0x100;