doc: add a "non stable" warning for parts which are not part

of the stable API yet and a couple of other minor doc updates...

Eigen/src/Core/util/Memory.h

@@ -44,7 +44,7 @@ template <typename T, int Size> struct ei_aligned_array<T,Size,false>
   T array[Size];
 };
 
-/** \internal allocates \a size * sizeof(\a T) bytes with a 16 bytes based alignment */
+/** \internal allocates \a size * sizeof(\a T) bytes with 16 bytes alignment */
 template<typename T>
 inline T* ei_aligned_malloc(size_t size)
 {
@@ -91,7 +91,7 @@ inline static int ei_alignmentOffset(const Scalar* ptr, int maxOffset)
 /** \internal
   * ei_alloc_stack(TYPE,SIZE) allocates sizeof(TYPE)*SIZE bytes on the stack if sizeof(TYPE)*SIZE is
   * smaller than EIGEN_STACK_ALLOCATION_LIMIT. Otherwise the memory is allocated using the operator new.
-  * Data allocated with ei_alloc_stack \b must be freed calling ei_free_stack(PTR,TYPE,SIZE).
+  * Data allocated with ei_alloc_stack \b must be freed by calling ei_free_stack(PTR,TYPE,SIZE).
   * \code
   * float * data = ei_alloc_stack(float,array.size());
   * // ...
@@ -108,15 +108,15 @@ inline static int ei_alignmentOffset(const Scalar* ptr, int maxOffset)
 
 /** \class WithAlignedOperatorNew
   *
-  * \brief Enforces inherited classes to be 16 bytes aligned when dynamicalled allocated with operator new
+  * \brief Enforces instances of inherited classes to be 16 bytes aligned when allocated with operator new
   *
   * When Eigen's explicit vectorization is enabled, Eigen assumes that some fixed sizes types are aligned
-  * on a 16 bytes boundary. Such types include:
+  * on a 16 bytes boundary. Those include all Matrix types having a sizeof multiple of 16 bytes, e.g.:
   *  - Vector2d, Vector4f, Vector4i, Vector4d,
   *  - Matrix2d, Matrix4f, Matrix4i, Matrix4d,
   *  - etc.
-  * When objects are statically allocated, the compiler will automatically and always enforces 16 bytes
+  * When an object is statically allocated, the compiler will automatically and always enforces 16 bytes
-  * alignment of the data. However some troubles might appear when data are dynamically allocated.
+  * alignment of the data when needed. However some troubles might appear when data are dynamically allocated.
   * Let's pick an example:
   * \code
   * struct Foo {
@@ -130,8 +130,8 @@ inline static int ei_alignmentOffset(const Scalar* ptr, int maxOffset)
   * pObj2->some_vector = Vector4f(..);  // =>  !! might segfault !!
   * \endcode
   * Here, the problem is that operator new is not aware of the compile time alignment requirement of the
-  * type Vector4f (and hence of the type Foo). Therefore "new Foo" does not necessarily returned a 16 bytes
+  * type Vector4f (and hence of the type Foo). Therefore "new Foo" does not necessarily returns a 16 bytes
-  * aligned pointer. The purpose of the class WithAlignedOperatorNew is exactly to overcome this issue, by
+  * aligned pointer. The purpose of the class WithAlignedOperatorNew is exactly to overcome this issue by
   * overloading the operator new to return aligned data when the vectorization is enabled.
   * Here is a similar safe example:
   * \code
@@ -139,12 +139,9 @@ inline static int ei_alignmentOffset(const Scalar* ptr, int maxOffset)
   *   char dummy;
   *   Vector4f some_vector;
   * };
-  * Foo obj1;                           // static allocation
-  * obj1.some_vector = Vector4f(..);    // =>   OK
-  *
   * Foo *pObj2 = new Foo;               // dynamic allocation
   * pObj2->some_vector = Vector4f(..);  // =>  SAFE !
-  * \endcode 
+  * \endcode
   *
   * \sa class ei_new_allocator
   */
@@ -172,7 +169,7 @@ struct WithAlignedOperatorNew
 
   void operator delete(void * ptr) { free(ptr); }
   void operator delete[](void * ptr) { free(ptr); }
-  
+
   #endif
 };
 
@@ -190,14 +187,14 @@ struct ei_with_aligned_operator_new<T,SizeAtCompileTime,false> {};
   * STL allocator simply wrapping operators new[] and delete[]. Unlike GCC's default new_allocator,
   * ei_new_allocator call operator new on the type \a T and not the general new operator ignoring
   * overloaded version of operator new.
-  * 
+  *
   * Example:
   * \code
   * // Vector4f requires 16 bytes alignment:
   * std::vector<Vector4f,ei_new_allocator<Vector4f> > dataVec4;
   * // Vector3f does not require 16 bytes alignment, no need to use Eigen's allocator:
   * std::vector<Vector3f> dataVec3;
-  * 
+  *
   * struct Foo : WithAlignedOperatorNew {
   *   char dummy;
   *   Vector4f some_vector;

Eigen/src/Geometry/AlignedBox.h

@@ -26,6 +26,7 @@
 #define EIGEN_ALIGNEDBOX_H
 
 /** \geometry_module \ingroup GeometryModule
+  * \nonstableyet
   *
   * \class AlignedBox
   *

Eigen/src/QR/EigenSolver.h

@@ -26,6 +26,7 @@
 #define EIGEN_EIGENSOLVER_H
 
 /** \ingroup QR_Module
+  * \nonstableyet
   *
   * \class EigenSolver
   *

Eigen/src/QR/HessenbergDecomposition.h

@@ -26,6 +26,7 @@
 #define EIGEN_HESSENBERGDECOMPOSITION_H
 
 /** \ingroup QR_Module
+  * \nonstableyet
   *
   * \class HessenbergDecomposition
   *

Eigen/src/QR/QR.h

@@ -26,6 +26,7 @@
 #define EIGEN_QR_H
 
 /** \ingroup QR_Module
+  * \nonstableyet
   *
   * \class QR
   *

Eigen/src/QR/SelfAdjointEigenSolver.h

@@ -26,6 +26,7 @@
 #define EIGEN_SELFADJOINTEIGENSOLVER_H
 
 /** \qr_module \ingroup QR_Module
+  * \nonstableyet
   *
   * \class SelfAdjointEigenSolver
   *
@@ -225,7 +226,7 @@ void SelfAdjointEigenSolver<MatrixType>::
 compute(const MatrixType& matA, const MatrixType& matB, bool computeEigenvectors)
 {
   ei_assert(matA.cols()==matA.rows() && matB.rows()==matA.rows() && matB.cols()==matB.rows());
-  
+
   // Compute the cholesky decomposition of matB = L L'
   LLT<MatrixType> cholB(matB);
 

Eigen/src/QR/Tridiagonalization.h

@@ -26,6 +26,7 @@
 #define EIGEN_TRIDIAGONALIZATION_H
 
 /** \ingroup QR_Module
+  * \nonstableyet
   *
   * \class Tridiagonalization
   *
@@ -219,7 +220,7 @@ void Tridiagonalization<MatrixType>::_compute(MatrixType& matA, CoeffVectorType&
       // i.e., A = H' A H where H = I - h v v' and v = matA.col(i).end(n-i-1)
 
       matA.col(i).coeffRef(i+1) = 1;
-      
+
       /* This is the initial algorithm which minimize operation counts and maximize
        * the use of Eigen's expression. Unfortunately, the first matrix-vector product
        * using Part<Lower|Selfadjoint>  is very very slow */
@@ -284,7 +285,7 @@ void Tridiagonalization<MatrixType>::_compute(MatrixType& matA, CoeffVectorType&
 
       hCoeffs.end(n-i-1) += (h * Scalar(-0.5) * matA.col(i).end(n-i-1).dot(hCoeffs.end(n-i-1)))
                             * matA.col(i).end(n-i-1);
-      
+
       const Scalar* EIGEN_RESTRICT pb = &matA.coeffRef(0,i);
       const Scalar* EIGEN_RESTRICT pa = (&hCoeffs.coeffRef(0)) - 1;
       for (int j1=i+1; j1<n; ++j1)
@@ -295,11 +296,11 @@ void Tridiagonalization<MatrixType>::_compute(MatrixType& matA, CoeffVectorType&
         {
           int alignedStart = (starti) + ei_alignmentOffset(&matA.coeffRef(starti,j1), n-starti);
           alignedEnd = alignedStart + ((n-alignedStart)/PacketSize)*PacketSize;
-          
+
           for (int i1=starti; i1<alignedStart; ++i1)
             matA.coeffRef(i1,j1) -= matA.coeff(i1,i)*ei_conj(hCoeffs.coeff(j1-1))
                                   + hCoeffs.coeff(i1-1)*ei_conj(matA.coeff(j1,i));
-          
+
           Packet tmp0 = ei_pset1(hCoeffs.coeff(j1-1));
           Packet tmp1 = ei_pset1(matA.coeff(j1,i));
           Scalar* pc = &matA.coeffRef(0,j1);

Eigen/src/SVD/SVD.h

@@ -26,6 +26,7 @@
 #define EIGEN_SVD_H
 
 /** \ingroup SVD_Module
+  * \nonstableyet
   *
   * \class SVD
   *

doc/Doxyfile.in

@@ -207,7 +207,8 @@ ALIASES                = "only_for_vectors=This is only for vectors (either row-
                          "regression_module=This is defined in the %Regression module. \code #include <Eigen/Regression> \endcode" \
                          "addexample=\anchor"  \
                          "label=\bug" \
-                         "redstar=<a href='#warningarraymodule' style='color:red;text-decoration: none;'><span style='color:red'>*</span></a>"
+                         "redstar=<a href='#warningarraymodule' style='color:red;text-decoration: none;'><span style='color:red'>*</span></a>" \
+                         "nonstableyet=\warning This class/function is not considered to be part of the stable public API yet. Some (minor) changes might happen in future releases."
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
 # sources only. Doxygen will then generate output that is more tailored for C.

doc/TutorialGeometry.dox

@@ -67,7 +67,7 @@ might still be interesting to write generic and efficient algorithms taking as i
 kind of transformations.
 
 Any of the above transformation types can be converted to any other types of the same nature,
-or to a more generic type. Here are come additional examples:
+or to a more generic type. Here are some additional examples:
 <table class="tutorial_code">
 <tr><td>\code
 Rotation2Df r = Matrix2f(..);       // assumes a pure rotation matrix
@@ -176,7 +176,7 @@ t.pretranslate(Vector_(tx,ty,..));
 t *= Translation_(tx,ty,..);
 t = Translation_(tx,ty,..) * t;
 \endcode</td></tr>
-<tr><td>\b Rotation \n <em class="note">In 2D, any_rotation can also \n be an angle in radian</em></td><td>\code
+<tr><td>\b Rotation \n <em class="note">In 2D and for the procedural API, any_rotation can also \n be an angle in radian</em></td><td>\code
 t.rotate(any_rotation);
 t.prerotate(any_rotation);
 \endcode</td><td>\code
@@ -216,7 +216,7 @@ t = Translation_(..) * t * RotationType(..) * Translation_(..) * Scaling_(..);
 <table class="tutorial_code">
 <tr><td style="max-width:30em;">
 Euler angles might be convenient to create rotation objects.
-On the other hand, since there exist 24 differents convensions,they are pretty confusing to use. This example shows how
+On the other hand, since there exist 24 differents convension,they are pretty confusing to use. This example shows how
 to create a rotation matrix according to the 2-1-2 convention.</td><td>\code
 Matrix3f m;
 m = AngleAxisf(angle1, Vector3f::UnitZ())