19 files changed, 87 insertions, 15 deletions

diff --git a/Eigen/Geometry b/Eigen/Geometry
index ae3012bfa..429dc2ac5 100644
--- a/Eigen/Geometry
+++ b/Eigen/Geometry
@@ -5,6 +5,8 @@
 
 namespace Eigen {
 
+/** \defgroup Geometry */
+
 #include "src/Geometry/Cross.h"
 #include "src/Geometry/Quaternion.h"
 #include "src/Geometry/AngleAxis.h"
diff --git a/Eigen/src/Array/Random.h b/Eigen/src/Array/Random.h
index 5cafb878a..97a34433a 100644
--- a/Eigen/src/Array/Random.h
+++ b/Eigen/src/Array/Random.h
@@ -44,6 +44,8 @@ struct ei_functor_traits<ei_scalar_random_op<Scalar> >
   * it is redundant to pass \a rows and \a cols as arguments, so ei_random() should be used
   * instead.
   *
+  * \addexample RandomExample \label How to create a matrix with random coefficients
+  *
   * Example: \include MatrixBase_random_int_int.cpp
   * Output: \verbinclude MatrixBase_random_int_int.out
   *
diff --git a/Eigen/src/Core/Block.h b/Eigen/src/Core/Block.h
index e7eb87a26..b185e90cf 100644
--- a/Eigen/src/Core/Block.h
+++ b/Eigen/src/Core/Block.h
@@ -341,6 +341,8 @@ template<typename MatrixType, int BlockRows, int BlockCols> class Block<MatrixTy
   * \param blockRows the number of rows in the block
   * \param blockCols the number of columns in the block
   *
+  * \addexample BlockIntIntIntInt \label How to reference a sub-matrix (dynamic-size)
+  *
   * Example: \include MatrixBase_block_int_int_int_int.cpp
   * Output: \verbinclude MatrixBase_block_int_int_int_int.out
   *
@@ -369,6 +371,8 @@ inline const Block<Derived> MatrixBase<Derived>
   *
   * \only_for_vectors
   *
+  * \addexample BlockIntInt \label How to reference a sub-vector (dynamic size)
+  *
   * \param start the first coefficient in the block
   * \param size the number of coefficients in the block
   *
@@ -410,6 +414,8 @@ inline const Block<Derived> MatrixBase<Derived>
   *
   * \param size the number of coefficients in the block
   *
+  * \addexample BlockInt \label How to reference a sub-vector (fixed-size)
+  *
   * Example: \include MatrixBase_start_int.cpp
   * Output: \verbinclude MatrixBase_start_int.out
   *
@@ -452,6 +458,8 @@ MatrixBase<Derived>::start(int size) const
   *
   * \param size the number of coefficients in the block
   *
+  * \addexample BlockEnd \label How to reference the end of a vector (fixed-size)
+  *
   * Example: \include MatrixBase_end_int.cpp
   * Output: \verbinclude MatrixBase_end_int.out
   *
@@ -498,6 +506,8 @@ MatrixBase<Derived>::end(int size) const
   *
   * The template parameter \a Size is the number of coefficients in the block
   *
+  * \addexample BlockStart \label How to reference the start of a vector (fixed-size)
+  *
   * Example: \include MatrixBase_template_int_start.cpp
   * Output: \verbinclude MatrixBase_template_int_start.out
   *
@@ -569,6 +579,8 @@ MatrixBase<Derived>::end() const
   * \param cRows the number of rows in the corner
   * \param cCols the number of columns in the corner
   *
+  * \addexample BlockCornerDynamicSize \label How to reference a sub-corner of a matrix
+  *
   * Example: \include MatrixBase_corner_enum_int_int.cpp
   * Output: \verbinclude MatrixBase_corner_enum_int_int.out
   *
@@ -678,6 +690,8 @@ inline const Block<Derived, CRows, CCols> MatrixBase<Derived>
   * \param startRow the first row in the block
   * \param startCol the first column in the block
   *
+  * \addexample BlockSubMatrixFixedSize \label How to reference a sub-matrix (fixed-size)
+  *
   * Example: \include MatrixBase_block_int_int.cpp
   * Output: \verbinclude MatrixBase_block_int_int.out
   *
@@ -705,6 +719,8 @@ inline const Block<Derived, BlockRows, BlockCols> MatrixBase<Derived>
 
 /** \returns an expression of the \a i-th column of *this. Note that the numbering starts at 0.
   *
+  * \addexample BlockColumn \label How to reference a single column of a matrix
+  *
   * Example: \include MatrixBase_col.cpp
   * Output: \verbinclude MatrixBase_col.out
   *
@@ -726,6 +742,8 @@ MatrixBase<Derived>::col(int i) const
 
 /** \returns an expression of the \a i-th row of *this. Note that the numbering starts at 0.
   *
+  * \addexample BlockRow \label How to reference a single row of a matrix
+  *
   * Example: \include MatrixBase_row.cpp
   * Output: \verbinclude MatrixBase_row.out
   *
diff --git a/Eigen/src/Core/CommaInitializer.h b/Eigen/src/Core/CommaInitializer.h
index 61a004780..137413a7c 100644
--- a/Eigen/src/Core/CommaInitializer.h
+++ b/Eigen/src/Core/CommaInitializer.h
@@ -113,6 +113,8 @@ struct MatrixBase<Derived>::CommaInitializer
   * The coefficients must be provided in a row major order and exactly match
   * the size of the matrix. Otherwise an assertion is raised.
   *
+  * \addexample CommaInit \label How to easily set all the coefficients of a matrix
+  *
   * Example: \include MatrixBase_set.cpp
   * Output: \verbinclude MatrixBase_set.out
   */
diff --git a/Eigen/src/Core/CwiseBinaryOp.h b/Eigen/src/Core/CwiseBinaryOp.h
index ba9304b64..8df4097c3 100644
--- a/Eigen/src/Core/CwiseBinaryOp.h
+++ b/Eigen/src/Core/CwiseBinaryOp.h
@@ -228,6 +228,8 @@ Cwise<ExpressionType>::max(const MatrixBase<OtherDerived> &other) const
   * The template parameter \a CustomBinaryOp is the type of the functor
   * of the custom operator (see class CwiseBinaryOp for an example)
   *
+  * \addexample CustomCwiseBinaryFunctors \label How to use custom coeff wise binary functors
+  *
   * Here is an example illustrating the use of custom functors:
   * \include class_CwiseBinaryOp.cpp
   * Output: \verbinclude class_CwiseBinaryOp.out
diff --git a/Eigen/src/Core/CwiseNullaryOp.h b/Eigen/src/Core/CwiseNullaryOp.h
index 3cf9070e2..6df351201 100644
--- a/Eigen/src/Core/CwiseNullaryOp.h
+++ b/Eigen/src/Core/CwiseNullaryOp.h
@@ -261,6 +261,8 @@ Derived& MatrixBase<Derived>::setConstant(const Scalar& value)
   * it is redundant to pass \a rows and \a cols as arguments, so zero() should be used
   * instead.
   *
+  * \addexample Zero \label How to take get a zero matrix
+  *
   * Example: \include MatrixBase_zero_int_int.cpp
   * Output: \verbinclude MatrixBase_zero_int_int.out
   *
@@ -356,6 +358,8 @@ Derived& MatrixBase<Derived>::setZero()
   * it is redundant to pass \a rows and \a cols as arguments, so ones() should be used
   * instead.
   *
+  * \addexample One \label How to get a matrix with all coefficients equal one
+  *
   * Example: \include MatrixBase_ones_int_int.cpp
   * Output: \verbinclude MatrixBase_ones_int_int.out
   *
@@ -446,6 +450,8 @@ Derived& MatrixBase<Derived>::setOnes()
   * This variant is meant to be used for dynamic-size matrix types. For fixed-size types,
   * it is redundant to pass \a rows and \a cols as arguments, so identity() should be used
   * instead.
+  * 
+  * \addexample Identity \label How to get an identity matrix
   *
   * Example: \include MatrixBase_identity_int_int.cpp
   * Output: \verbinclude MatrixBase_identity_int_int.out
diff --git a/Eigen/src/Core/CwiseUnaryOp.h b/Eigen/src/Core/CwiseUnaryOp.h
index 77dcaa350..b5a9e4d91 100644
--- a/Eigen/src/Core/CwiseUnaryOp.h
+++ b/Eigen/src/Core/CwiseUnaryOp.h
@@ -109,6 +109,8 @@ class CwiseUnaryOp : ei_no_assignment_operator,
   * The template parameter \a CustomUnaryOp is the type of the functor
   * of the custom unary operator.
   *
+  * \addexample CustomCwiseUnaryFunctors \label How to use custom coeff wise unary functors
+  *
   * Here is an example:
   * \include class_CwiseUnaryOp.cpp
   * Output: \verbinclude class_CwiseUnaryOp.out
diff --git a/Eigen/src/Core/DiagonalMatrix.h b/Eigen/src/Core/DiagonalMatrix.h
index 34bd7ebf3..029e273e5 100644
--- a/Eigen/src/Core/DiagonalMatrix.h
+++ b/Eigen/src/Core/DiagonalMatrix.h
@@ -84,6 +84,8 @@ class DiagonalMatrix : ei_no_assignment_operator,
   *
   * \only_for_vectors
   *
+  * \addexample AsDiagonalExample \label How to build a diagonal matrix from a vector
+  *
   * Example: \include MatrixBase_asDiagonal.cpp
   * Output: \verbinclude MatrixBase_asDiagonal.out
   *
diff --git a/Eigen/src/Core/Extract.h b/Eigen/src/Core/Extract.h
index 516178c2c..ff84d0ece 100755
--- a/Eigen/src/Core/Extract.h
+++ b/Eigen/src/Core/Extract.h
@@ -94,6 +94,8 @@ template<typename MatrixType, unsigned int Mode> class Extract
   * The parameter \a Mode can have the following values: \c Upper, \c StrictlyUpper, \c UnitUpper,
   * \c Lower, \c StrictlyLower, \c UnitLower.
   *
+  * \addexample ExtractExample \label How to extract a triangular part of an arbitrary matrix
+  *
   * Example: \include MatrixBase_extract.cpp
   * Output: \verbinclude MatrixBase_extract.out
   *
diff --git a/Eigen/src/Core/Flagged.h b/Eigen/src/Core/Flagged.h
index 2b26e3016..a6abe617b 100644
--- a/Eigen/src/Core/Flagged.h
+++ b/Eigen/src/Core/Flagged.h
@@ -121,6 +121,8 @@ template<typename ExpressionType, unsigned int Added, unsigned int Removed> clas
 
 /** \returns an expression of *this with added flags
   *
+  * \addexample MarkExample \label How to mark a triangular matrix as triangular
+  *
   * Example: \include MatrixBase_marked.cpp
   * Output: \verbinclude MatrixBase_marked.out
   *
diff --git a/Eigen/src/Geometry/AngleAxis.h b/Eigen/src/Geometry/AngleAxis.h
index 639e75a87..abb9b50f6 100644
--- a/Eigen/src/Geometry/AngleAxis.h
+++ b/Eigen/src/Geometry/AngleAxis.h
@@ -25,9 +25,11 @@
 #ifndef EIGEN_ANGLEAXIS_H
 #define EIGEN_ANGLEAXIS_H
 
-/** \class AngleAxis
+/** \geometry_module \ingroup Geometry
   *
-  * \brief Represents a rotation in a 3 dimensional space as a rotation angle around a 3D axis
+  * \class AngleAxis
+  *
+  * \brief Represents a 3D rotation as a rotation angle around an arbitray 3D axis
   *
   * \param _Scalar the scalar type, i.e., the type of the coefficients.
   *
@@ -35,7 +37,7 @@
   * \li \c AngleAxisf for \c float
   * \li \c AngleAxisd for \c double
   *
-  * \sa class Quaternion, class EulerAngles, class Transform
+  * \sa class Quaternion, class Transform
   */
 template<typename _Scalar>
 class AngleAxis
diff --git a/Eigen/src/Geometry/Cross.h b/Eigen/src/Geometry/Cross.h
index 61b630c2a..ab8f7528c 100644
--- a/Eigen/src/Geometry/Cross.h
+++ b/Eigen/src/Geometry/Cross.h
@@ -25,7 +25,8 @@
 #ifndef EIGEN_CROSS_H
 #define EIGEN_CROSS_H
 
-/** \returns the cross product of \c *this and \a other */
+/** \geometry_module
+  * \returns the cross product of \c *this and \a other */
 template<typename Derived>
 template<typename OtherDerived>
 inline typename ei_eval<Derived>::type
diff --git a/Eigen/src/Geometry/Quaternion.h b/Eigen/src/Geometry/Quaternion.h
index fcc7e21ca..1d31e2f96 100644
--- a/Eigen/src/Geometry/Quaternion.h
+++ b/Eigen/src/Geometry/Quaternion.h
@@ -30,7 +30,9 @@ template<typename Other,
          int OtherCols=Other::ColsAtCompileTime>
 struct ei_quaternion_assign_impl;
 
-/** \class Quaternion
+/** \geometry_module \ingroup Geometry
+  *
+  * \class Quaternion
   *
   * \brief The quaternion class used to represent 3D orientations and rotations
   *
@@ -48,7 +50,7 @@ struct ei_quaternion_assign_impl;
   * \li \c Quaternionf for \c float
   * \li \c Quaterniond for \c double
   *
-  * \sa  class AngleAxis, class EulerAngles, class Transform
+  * \sa  class AngleAxis, class Transform
   */
 template<typename _Scalar>
 class Quaternion
diff --git a/Eigen/src/Geometry/Rotation.h b/Eigen/src/Geometry/Rotation.h
index fb4179786..e0855b739 100644
--- a/Eigen/src/Geometry/Rotation.h
+++ b/Eigen/src/Geometry/Rotation.h
@@ -28,7 +28,9 @@
 // this file aims to contains the various representations of rotation/orientation
 // in 2D and 3D space excepted Matrix and Quaternion.
 
-/** \class ToRotationMatrix
+/** \geometry_module
+  *
+  * \class ToRotationMatrix
   *
   * \brief Template static struct to convert any rotation representation to a matrix form
   *
@@ -101,7 +103,9 @@ struct ToRotationMatrix<Scalar, Dim, MatrixBase<OtherDerived> >
   }
 };
 
-/** \class Rotation2D
+/** \geometry_module
+  *
+  * \class Rotation2D
   *
   * \brief Represents a rotation/orientation in a 2 dimensional space.
   *
diff --git a/Eigen/src/Geometry/Transform.h b/Eigen/src/Geometry/Transform.h
index 4428e3c74..7669838de 100644
--- a/Eigen/src/Geometry/Transform.h
+++ b/Eigen/src/Geometry/Transform.h
@@ -35,7 +35,9 @@ template< typename Other,
           int OtherCols=Other::ColsAtCompileTime>
 struct ei_transform_product_impl;
 
-/** \class Transform
+/** \geometry_module \ingroup Geometry
+  *
+  * \class Transform
   *
   * \brief Represents an homogeneous transformation in a N dimensional space
   *
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 4e1a7696d..10d762a21 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -20,6 +20,7 @@ ADD_SUBDIRECTORY(snippets)
 ADD_CUSTOM_TARGET(
   run_doxygen
   ALL
+  COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/buildexamplelist.sh ${CMAKE_SOURCE_DIR} > ${CMAKE_CURRENT_BINARY_DIR}/ExampleList.dox
   COMMAND doxygen
   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
 )
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 64bd2b3f7..bade60a2b 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -197,9 +197,12 @@ TAB_SIZE               = 8
 # You can put \n's in the value part of an alias to insert newlines.
 
 ALIASES                = "only_for_vectors=This is only for vectors (either row-vectors or column-vectors), i.e. matrices which are known at compile-time to have either one row or one column." \
-                         "array_module=This is defined in the %Array module. \code #include<Eigen/Array> \endcode" \
-                         "lu_module=This is defined in the %LU module. \code #include<Eigen/LU> \endcode" \
-                         "qr_module=This is defined in the %QR module. \code #include<Eigen/QR> \endcode"
+                         "array_module=This is defined in the %Array module. \code #include <Eigen/Array> \endcode" \
+                         "lu_module=This is defined in the %LU module. \code #include <Eigen/LU> \endcode" \
+                         "qr_module=This is defined in the %QR module. \code #include <Eigen/QR> \endcode" \
+                         "geometry_module=This is defined in the %Geometry module. \code #include <Eigen/Geometry> \endcode" \
+                         "addexample=\anchor"  \
+                         "label=\bug"
 # 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.
 # For instance, some of the names that are used will be different. The list
@@ -547,7 +550,8 @@ WARN_LOGFILE           =
 # with spaces.
 
 INPUT                  = ${CMAKE_SOURCE_DIR}/Eigen \
-                         ${CMAKE_SOURCE_DIR}/doc
+                         ${CMAKE_SOURCE_DIR}/doc \
+                         ${CMAKE_BINARY_DIR}/doc
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -576,7 +580,7 @@ RECURSIVE              = NO
 # excluded from the INPUT source files. This way you can easily exclude a
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                =
+EXCLUDE                = 
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
 # directories that are symbolic links (a Unix filesystem feature) are excluded
@@ -592,6 +596,7 @@ EXCLUDE_SYMLINKS       = NO
 
 EXCLUDE_PATTERNS       = CMake* \
                          *.txt \
+                         *.sh \
                          *~
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
diff --git a/doc/Mainpage.dox b/doc/Mainpage.dox
index 2437872b0..aef72b042 100644
--- a/doc/Mainpage.dox
+++ b/doc/Mainpage.dox
@@ -6,7 +6,7 @@ This is the API documentation for Eigen.
 
 Most of the API is available as methods in MatrixBase, so this is a good starting point for browsing. Also have a look at Matrix, as a few methods and the matrix constructors are there. Other notable classes for the Eigen API are Cwise, which contains the methods for doing certain coefficient-wise operations, and Part.
 
-For a first contact with Eigen, it is enough to look at Matrix, MatrixBase, and Cwise. In fact, except for advanced use, the only class that you'll have to explicitly name in your program, i.e. of which you'll explicitly contruct objects, is Matrix. For instance, vectors are handled as a special case of Matrix with one column. Typedefs are provided, e.g. Vector2f is a typedef for Matrix<float, 2, 1>.
+For a first contact with Eigen, you might look at the \ref ExampleList "the list of selected examples". Then, it is enough to look at Matrix, MatrixBase, and Cwise. In fact, except for advanced use, the only class that you'll have to explicitly name in your program, i.e. of which you'll explicitly contruct objects, is Matrix. For instance, vectors are handled as a special case of Matrix with one column. Typedefs are provided, e.g. Vector2f is a typedef for Matrix<float, 2, 1>.
 
 Most of the other classes are just return types for MatrixBase methods.
 
diff --git a/doc/buildexamplelist.sh b/doc/buildexamplelist.sh
new file mode 100755
index 000000000..0a9bb7ec0
--- /dev/null
+++ b/doc/buildexamplelist.sh
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+echo "namespace Eigen {"
+echo "/** \page ExampleList"
+echo "<h1>Selected list of examples</h1>"
+
+grep \\addexample $1/Eigen/* -R | cut -d \\ -f 2- | \
+while read example;
+do
+anchor=`echo "$example" | cut -d " " -f 2`
+text=`echo "$example" | cut -d " " -f 4-`
+echo "\\\li \\\ref $anchor \"$text\""
+done
+echo "*/"
+echo "}"
\ No newline at end of file