Extend doc page on preprocessor directives.

2 files changed, 72 insertions, 12 deletions

diff --git a/doc/I10_Assertions.dox b/doc/I10_Assertions.dox
index 0370abc70..d5697fcee 100644
--- a/doc/I10_Assertions.dox
+++ b/doc/I10_Assertions.dox
@@ -7,5 +7,7 @@ TODO: write this dox page!
 
 Is linked from the tutorial on matrix arithmetic.
 
+\sa Section \ref TopicPreprocessorDirectivesAssertions on page \ref TopicPreprocessorDirectives.
+
 */
 }
diff --git a/doc/I14_PreprocessorDirectives.dox b/doc/I14_PreprocessorDirectives.dox
index 0c8804020..7f9043134 100644
--- a/doc/I14_PreprocessorDirectives.dox
+++ b/doc/I14_PreprocessorDirectives.dox
@@ -2,18 +2,76 @@ namespace Eigen {
 
 /** \page TopicPreprocessorDirectives Preprocessor directives
 
-You can control some aspects of Eigen by defining the following preprocessor tokens them before including any of Eigen's headers.
- - \b EIGEN_NO_DEBUG If defined, Eigen's assertions are disabled. Disabling run-time assertions improves the
-   performance, but it is dangerous because the assertions guard against programming errors. By default, the
-   EIGEN_NO_DEBUG macro is not defined and Eigen's run-time assertions are thus enabled. However, if the
-   NDEBUG macro is defined (this is a standard C++ macro which disables all asserts), then the EIGEN_NO_DEBUG
-   macro will also be defined, and so Eigen's assertions will also be disabled. 
- - \b EIGEN_DONT_VECTORIZE disables explicit vectorization when defined.
- - \b EIGEN_UNROLLING_LIMIT defines the maximal instruction counts to enable meta unrolling of loops. Set it to zero to disable unrolling. The default is 100.
- - \b EIGEN_DEFAULT_TO_ROW_MAJOR the default storage order for matrices becomes row-major instead of column-major.
- - \b EIGEN_TUNE_FOR_CPU_CACHE_SIZE represents the maximal size in Bytes of L2 blocks. Since several blocks have to stay concurently in L2 cache, this value should correspond to at most 1/4 of the size of L2 cache.
- - \b EIGEN_NO_STATIC_ASSERT replaces compile time static assertions by runtime assertions
- - \b EIGEN_MATRIXBASE_PLUGIN see \ref ExtendingMatrixBase
+You can control some aspects of Eigen by defining the preprocessor tokens using \c #define. These macros
+should be defined before any Eigen headers are included. Often they are best set in the project options.
+
+This page lists the preprocesor tokens recognised by Eigen.
+
+<b>Table of contents</b>
+  - \ref TopicPreprocessorDirectivesMajor
+  - \ref TopicPreprocessorDirectivesAssertions
+  - \ref TopicPreprocessorDirectivesPerformance
+  - \ref TopicPreprocessorDirectivesPlugins
+
+
+\section TopicPreprocessorDirectivesMajor Macros with major effects
+
+ - \b EIGEN2_SUPPORT - if defined, enables the Eigen2 compatibility mode. This is meant to ease the transition
+   of Eigen2 to Eigen3 (see \ref Eigen2ToEigen3). Not defined by default.
+ - \b EIGEN_DEFAULT_TO_ROW_MAJOR - when defined, the default storage order for matrices becomes row-major
+   instead of column-major. Not defined by default.
+ - \b EIGEN_DEFAULT_IO_FORMAT - the IOFormat to use when printing a matrix if no #IOFormat is specified.
+   Defaults to the #IOFormat constructed by the default constructor IOFormat().
+ - \b EIGEN_INITIALIZE_MATRICES_BY_ZERO - if defined, all entries of newly constructed matrices and arrays are
+   initializes to zero, as are new entries in matrices and arrays after resizing. Not defined by default.
+
+
+\section TopicPreprocessorDirectivesAssertions Assertions
+
+The Eigen library contains many assertions to guard against programming errors, both at compile time and at
+run time. However, these assertions do cost time and can thus be turned off.
+
+ - \b EIGEN_NO_DEBUG - disables Eigen's assertions if defined. Not defined by default, unless the
+   \c NDEBUG macro is defined (this is a standard C++ macro which disables all asserts). 
+ - \b EIGEN_NO_STATIC_ASSERT - if defined, compile-time static assertions are replaced by runtime assertions; 
+   this saves compilation time. Not defined by default.
+ - \b EIGEN_INTERNAL_DEBUGGING - if defined, enables assertions in Eigen's internal routines. This is useful
+   for debugging Eigen itself. Not defined by default.
+
+
+\section TopicPreprocessorDirectivesPerformance Alignment, vectorization and performance tweaking
+
+ - \b EIGEN_DONT_ALIGN - disables alignment.
+ - \b EIGEN_DONT_ALIGN_STATICALLY - disables alignment of arrays on the stack. Not defined by default, unless
+   \c EIGEN_DONT_ALIGN is defined.
+ - \b EIGEN_DONT_VECTORIZE - disables explicit vectorization when defined. Not defined by default, unless 
+   alignment is disabled by Eigen's platform test or the user defining \c EIGEN_DONT_ALIGN.
+ - \b EIGEN_FAST_MATH - enables some optimizations which might affect the accuracy of the result. The only
+   optimization this currently includes is single precision sin() and cos() in the present of SSE
+   vectorization. Defined by default. 
+ - \b EIGEN_UNROLLING_LIMIT - defines the size of a loop to enable meta unrolling. Set it to zero to disable
+   unrolling. The size of a loop 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. The default is value 100. 
+ - \b EIGEN_TUNE_FOR_CPU_CACHE_SIZE - represents the maximal size in Bytes of L2 blocks. Since several blocks
+   have to stay concurently in L2 cache, this value should correspond to at most 1/4 of the size of L2 cache. 
+
+
+\section TopicPreprocessorDirectivesPlugins Plugins
+
+It is possible to add new methods to many fundamental classes in Eigen by writing a plugin. As explained in
+the section \ref ExtendingMatrixBase, the plugin is specified by defining a \c EIGEN_xxx_PLUGIN macro. The
+following macros are supported; none of them are defined by default.
+
+ - \b EIGEN_ARRAYBASE_PLUGIN - filename of plugin for extending the ArrayBase class.
+ - \b EIGEN_ARRAY_PLUGIN - filename of plugin for extending the Array class.
+ - \b EIGEN_CWISE_PLUGIN - filename of plugin for extending the Cwise class.
+ - \b EIGEN_DENSEBASE_PLUGIN - filename of plugin for extending the DenseBase class.
+ - \b EIGEN_DENSESTORAGEBASE_PLUGIN - filename of plugin for extending the PlainObjectBase class.
+ - \b EIGEN_MATRIXBASE_PLUGIN - filename of plugin for extending the MatrixBase class.
+ - \b EIGEN_MATRIX_PLUGIN - filename of plugin for extending the Matrix class.
+ - \b EIGEN_QUATERNIONBASE_PLUGIN - filename of plugin for extending the QuaternionBase class.
+ - \b EIGEN_TRANSFORM_PLUGIN - filename of plugin for extending the Transform class.
+ - \b EIGEN_FUNCTORS_PLUGIN - filename of plugin for adding new functors and specializations of functor_traits.
 
 */