Move documentation of MatrixBase methods in MatrixFunctions to module page.

I think that because MatrixFunctions is in unsupported/ and MatrixBase is
not, doxygen does not include the MatrixBase methods defined and documented
in the MatrixFunctions module with the other MatrixBase methods. This is a
kludge, but at least the documentation is not lost.

3 files changed, 209 insertions, 150 deletions

diff --git a/unsupported/Eigen/MatrixFunctions b/unsupported/Eigen/MatrixFunctions
index 292357fda..e0bc4732c 100644
--- a/unsupported/Eigen/MatrixFunctions
+++ b/unsupported/Eigen/MatrixFunctions
@@ -40,6 +40,22 @@ namespace Eigen {
   * \brief This module aims to provide various methods for the computation of
   * matrix functions. 
   *
+  * To use this module, add 
+  * \code
+  * #include <unsupported/Eigen/MatrixFunctions>
+  * \endcode
+  * at the start of your source file.
+  *
+  * This module defines the following MatrixBase methods.
+  *  - \ref matrixbase_cos "MatrixBase::cos()", for computing the matrix cosine
+  *  - \ref matrixbase_cosh "MatrixBase::cosh()", for computing the matrix hyperbolic cosine
+  *  - \ref matrixbase_exp "MatrixBase::exp()", for computing the matrix exponential
+  *  - \ref matrixbase_matrixfunction "MatrixBase::matrixFunction()", for computing general matrix functions
+  *  - \ref matrixbase_sin "MatrixBase::sin()", for computing the matrix sine
+  *  - \ref matrixbase_sinh "MatrixBase::sinh()", for computing the matrix hyperbolic sine
+  *
+  * These methods are the main entry points to this module. 
+  *
   * %Matrix functions are defined as follows.  Suppose that \f$ f \f$
   * is an entire function (that is, a function on the complex plane
   * that is everywhere complex differentiable).  Then its Taylor
@@ -49,16 +65,205 @@ namespace Eigen {
   * function by the same series:
   * \f[ f(M) = f(0) + f'(0) M + \frac{f''(0)}{2} M^2 + \frac{f'''(0)}{3!} M^3 + \cdots \f]
   *
-  * \code
-  * #include <unsupported/Eigen/MatrixFunctions>
-  * \endcode
   */
 
 #include "src/MatrixFunctions/MatrixExponential.h"
 #include "src/MatrixFunctions/MatrixFunction.h"
 
-}
 
 
+/** 
+\page matrixbaseextra MatrixBase methods defined in the MatrixFunctions module
+\ingroup MatrixFunctions_Module
+
+The remainder of the page documents the following MatrixBase methods
+which are defined in the MatrixFunctions module.
+
+
+
+\section matrixbase_cos MatrixBase::cos()
+
+Compute the matrix cosine.
+
+\code
+const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cos() const
+\endcode
+
+\param[in]  M  a square matrix.
+\returns  expression representing \f$ \cos(M) \f$.
+
+This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::cos().
+
+\sa \ref matrixbase_sin "sin()" for an example.
+
+
+
+\section matrixbase_cosh MatrixBase::cosh()
+
+Compute the matrix hyberbolic cosine.
+
+\code
+const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cosh() const
+\endcode
+
+\param[in]  M  a square matrix.
+\returns  expression representing \f$ \cosh(M) \f$
+
+This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::cosh().
+
+\sa \ref matrixbase_sinh "sinh()" for an example.
+
+
+
+\section matrixbase_exp MatrixBase::exp()
+
+Compute the matrix exponential.
+
+\code
+const MatrixExponentialReturnValue<Derived> MatrixBase<Derived>::exp() const
+\endcode
+
+\param[in]  M  matrix whose exponential is to be computed.
+\returns    expression representing the matrix exponential of \p M.
+
+The matrix exponential of \f$ M \f$ is defined by
+\f[ \exp(M) = \sum_{k=0}^\infty \frac{M^k}{k!}. \f]
+The matrix exponential can be used to solve linear ordinary
+differential equations: the solution of \f$ y' = My \f$ with the
+initial condition \f$ y(0) = y_0 \f$ is given by
+\f$ y(t) = \exp(M) y_0 \f$.
+
+The cost of the computation is approximately \f$ 20 n^3 \f$ for
+matrices of size \f$ n \f$. The number 20 depends weakly on the
+norm of the matrix.
+
+The matrix exponential is computed using the scaling-and-squaring
+method combined with Pad&eacute; approximation. The matrix is first
+rescaled, then the exponential of the reduced matrix is computed
+approximant, and then the rescaling is undone by repeated
+squaring. The degree of the Pad&eacute; approximant is chosen such
+that the approximation error is less than the round-off
+error. However, errors may accumulate during the squaring phase.
+
+Details of the algorithm can be found in: Nicholas J. Higham, "The
+scaling and squaring method for the matrix exponential revisited,"
+<em>SIAM J. %Matrix Anal. Applic.</em>, <b>26</b>:1179&ndash;1193,
+2005.
+
+Example: The following program checks that
+\f[ \exp \left[ \begin{array}{ccc}
+      0 & \frac14\pi & 0 \\
+      -\frac14\pi & 0 & 0 \\
+      0 & 0 & 0
+    \end{array} \right] = \left[ \begin{array}{ccc}
+      \frac12\sqrt2 & -\frac12\sqrt2 & 0 \\
+      \frac12\sqrt2 & \frac12\sqrt2 & 0 \\
+      0 & 0 & 1
+    \end{array} \right]. \f]
+This corresponds to a rotation of \f$ \frac14\pi \f$ radians around
+the z-axis.
+
+\include MatrixExponential.cpp
+Output: \verbinclude MatrixExponential.out
+
+\note \p M has to be a matrix of \c float, \c double,
+\c complex<float> or \c complex<double> .
+
+
+
+\section matrixbase_matrixfunction MatrixBase::matrixFunction()
+
+Compute a matrix function.
+
+\code
+const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::matrixFunction(typename ei_stem_function<typename ei_traits<Derived>::Scalar>::type f) const
+\endcode
+
+\param[in]  M  argument of matrix function, should be a square matrix.
+\param[in]  f  an entire function; \c f(x,n) should compute the n-th
+derivative of f at x.
+\returns  expression representing \p f applied to \p M.
+
+Suppose that \p M is a matrix whose entries have type \c Scalar. 
+Then, the second argument, \p f, should be a function with prototype
+\code 
+ComplexScalar f(ComplexScalar, int) 
+\endcode
+where \c ComplexScalar = \c std::complex<Scalar> if \c Scalar is
+real (e.g., \c float or \c double) and \c ComplexScalar =
+\c Scalar if \c Scalar is complex. The return value of \c f(x,n)
+should be \f$ f^{(n)}(x) \f$, the n-th derivative of f at x.
+
+This routine uses the algorithm described in:
+Philip Davies and Nicholas J. Higham, 
+"A Schur-Parlett algorithm for computing matrix functions", 
+<em>SIAM J. %Matrix Anal. Applic.</em>, <b>25</b>:464&ndash;485, 2003.
+
+The actual work is done by the MatrixFunction class.
+
+Example: The following program checks that
+\f[ \exp \left[ \begin{array}{ccc} 
+      0 & \frac14\pi & 0 \\ 
+      -\frac14\pi & 0 & 0 \\
+      0 & 0 & 0 
+    \end{array} \right] = \left[ \begin{array}{ccc}
+      \frac12\sqrt2 & -\frac12\sqrt2 & 0 \\
+      \frac12\sqrt2 & \frac12\sqrt2 & 0 \\
+      0 & 0 & 1
+    \end{array} \right]. \f]
+This corresponds to a rotation of \f$ \frac14\pi \f$ radians around
+the z-axis. This is the same example as used in the documentation
+of \ref matrixbase_exp "exp()".
+
+\include MatrixFunction.cpp
+Output: \verbinclude MatrixFunction.out
+
+Note that the function \c expfn is defined for complex numbers 
+\c x, even though the matrix \c A is over the reals. Instead of
+\c expfn, we could also have used StdStemFunctions::exp:
+\code
+A.matrixFunction(StdStemFunctions<std::complex<double> >::exp, &B);
+\endcode
+
+
+
+\section matrixbase_sin MatrixBase::sin()
+
+Compute the matrix sine.
+
+\code
+const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sin() const
+\endcode
+
+\param[in]  M  a square matrix.
+\returns  expression representing \f$ \sin(M) \f$.
+
+This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::sin().
+
+Example: \include MatrixSine.cpp
+Output: \verbinclude MatrixSine.out
+
+
+
+\section matrixbase_sinh const MatrixBase::sinh()
+
+Compute the matrix hyperbolic sine.
+
+\code
+MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sinh() const
+\endcode
+
+\param[in]  M  a square matrix.
+\returns  expression representing \f$ \sinh(M) \f$
+
+This function calls \ref matrixbase_matrixfunction "matrixFunction()" with StdStemFunctions::sinh().
+
+Example: \include MatrixSinh.cpp
+Output: \verbinclude MatrixSinh.out
+
+*/
+
+}
+
 #endif // EIGEN_MATRIX_FUNCTIONS
 
diff --git a/unsupported/Eigen/src/MatrixFunctions/MatrixExponential.h b/unsupported/Eigen/src/MatrixFunctions/MatrixExponential.h
index 3ef91a7b2..d7eb1b2fe 100644
--- a/unsupported/Eigen/src/MatrixFunctions/MatrixExponential.h
+++ b/unsupported/Eigen/src/MatrixFunctions/MatrixExponential.h
@@ -330,56 +330,6 @@ struct ei_traits<MatrixExponentialReturnValue<Derived> >
   typedef typename Derived::PlainObject ReturnType;
 };
 
-/** \ingroup MatrixFunctions_Module
- *
- * \brief Compute the matrix exponential.
- *
- * \param[in]  M  matrix whose exponential is to be computed.
- * \returns    expression representing the matrix exponential of \p M.
- *
- * The matrix exponential of \f$ M \f$ is defined by
- * \f[ \exp(M) = \sum_{k=0}^\infty \frac{M^k}{k!}. \f]
- * The matrix exponential can be used to solve linear ordinary
- * differential equations: the solution of \f$ y' = My \f$ with the
- * initial condition \f$ y(0) = y_0 \f$ is given by
- * \f$ y(t) = \exp(M) y_0 \f$.
- *
- * The cost of the computation is approximately \f$ 20 n^3 \f$ for
- * matrices of size \f$ n \f$. The number 20 depends weakly on the
- * norm of the matrix.
- *
- * The matrix exponential is computed using the scaling-and-squaring
- * method combined with Pad&eacute; approximation. The matrix is first
- * rescaled, then the exponential of the reduced matrix is computed
- * approximant, and then the rescaling is undone by repeated
- * squaring. The degree of the Pad&eacute; approximant is chosen such
- * that the approximation error is less than the round-off
- * error. However, errors may accumulate during the squaring phase.
- *
- * Details of the algorithm can be found in: Nicholas J. Higham, "The
- * scaling and squaring method for the matrix exponential revisited,"
- * <em>SIAM J. %Matrix Anal. Applic.</em>, <b>26</b>:1179&ndash;1193,
- * 2005.
- *
- * Example: The following program checks that
- * \f[ \exp \left[ \begin{array}{ccc}
- *       0 & \frac14\pi & 0 \\
- *       -\frac14\pi & 0 & 0 \\
- *       0 & 0 & 0
- *     \end{array} \right] = \left[ \begin{array}{ccc}
- *       \frac12\sqrt2 & -\frac12\sqrt2 & 0 \\
- *       \frac12\sqrt2 & \frac12\sqrt2 & 0 \\
- *       0 & 0 & 1
- *     \end{array} \right]. \f]
- * This corresponds to a rotation of \f$ \frac14\pi \f$ radians around
- * the z-axis.
- *
- * \include MatrixExponential.cpp
- * Output: \verbinclude MatrixExponential.out
- *
- * \note \p M has to be a matrix of \c float, \c double,
- * \c complex<float> or \c complex<double> .
- */
 template <typename Derived>
 const MatrixExponentialReturnValue<Derived> MatrixBase<Derived>::exp() const
 {
diff --git a/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h b/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h
index 72e42aa7c..270d23b8b 100644
--- a/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h
+++ b/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h
@@ -536,56 +536,6 @@ struct ei_traits<MatrixFunctionReturnValue<Derived> >
 /********** MatrixBase methods **********/
 
 
-/** \ingroup MatrixFunctions_Module
-  *
-  * \brief Compute a matrix function.
-  *
-  * \param[in]  M  argument of matrix function, should be a square matrix.
-  * \param[in]  f  an entire function; \c f(x,n) should compute the n-th
-  * derivative of f at x.
-  * \returns  expression representing \p f applied to \p M.
-  *
-  * Suppose that \p M is a matrix whose entries have type \c Scalar. 
-  * Then, the second argument, \p f, should be a function with prototype
-  * \code 
-  * ComplexScalar f(ComplexScalar, int) 
-  * \endcode
-  * where \c ComplexScalar = \c std::complex<Scalar> if \c Scalar is
-  * real (e.g., \c float or \c double) and \c ComplexScalar =
-  * \c Scalar if \c Scalar is complex. The return value of \c f(x,n)
-  * should be \f$ f^{(n)}(x) \f$, the n-th derivative of f at x.
-  *
-  * This routine uses the algorithm described in:
-  * Philip Davies and Nicholas J. Higham, 
-  * "A Schur-Parlett algorithm for computing matrix functions", 
-  * <em>SIAM J. %Matrix Anal. Applic.</em>, <b>25</b>:464&ndash;485, 2003.
-  *
-  * The actual work is done by the MatrixFunction class.
-  *
-  * Example: The following program checks that
-  * \f[ \exp \left[ \begin{array}{ccc} 
-  *       0 & \frac14\pi & 0 \\ 
-  *       -\frac14\pi & 0 & 0 \\
-  *       0 & 0 & 0 
-  *     \end{array} \right] = \left[ \begin{array}{ccc}
-  *       \frac12\sqrt2 & -\frac12\sqrt2 & 0 \\
-  *       \frac12\sqrt2 & \frac12\sqrt2 & 0 \\
-  *       0 & 0 & 1
-  *     \end{array} \right]. \f]
-  * This corresponds to a rotation of \f$ \frac14\pi \f$ radians around
-  * the z-axis. This is the same example as used in the documentation
-  * of MatrixBase::exp().
-  *
-  * \include MatrixFunction.cpp
-  * Output: \verbinclude MatrixFunction.out
-  *
-  * Note that the function \c expfn is defined for complex numbers 
-  * \c x, even though the matrix \c A is over the reals. Instead of
-  * \c expfn, we could also have used StdStemFunctions::exp:
-  * \code
-  * A.matrixFunction(StdStemFunctions<std::complex<double> >::exp, &B);
-  * \endcode
-  */
 template <typename Derived>
 const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::matrixFunction(typename ei_stem_function<typename ei_traits<Derived>::Scalar>::type f) const
 {
@@ -593,18 +543,6 @@ const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::matrixFunction(typ
   return MatrixFunctionReturnValue<Derived>(derived(), f);
 }
 
-/** \ingroup MatrixFunctions_Module
-  *
-  * \brief Compute the matrix sine.
-  *
-  * \param[in]  M  a square matrix.
-  * \returns  expression representing \f$ \sin(M) \f$.
-  * 
-  * This function calls matrixFunction() with StdStemFunctions::sin().
-  *
-  * \include MatrixSine.cpp
-  * Output: \verbinclude MatrixSine.out
-  */
 template <typename Derived>
 const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sin() const
 {
@@ -613,17 +551,6 @@ const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sin() const
   return MatrixFunctionReturnValue<Derived>(derived(), StdStemFunctions<ComplexScalar>::sin);
 }
 
-/** \ingroup MatrixFunctions_Module
-  *
-  * \brief Compute the matrix cosine.
-  *
-  * \param[in]  M  a square matrix.
-  * \returns  expression representing \f$ \cos(M) \f$.
-  * 
-  * This function calls matrixFunction() with StdStemFunctions::cos().
-  *
-  * \sa ei_matrix_sin() for an example.
-  */
 template <typename Derived>
 const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cos() const
 {
@@ -632,18 +559,6 @@ const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cos() const
   return MatrixFunctionReturnValue<Derived>(derived(), StdStemFunctions<ComplexScalar>::cos);
 }
 
-/** \ingroup MatrixFunctions_Module
-  *
-  * \brief Compute the matrix hyperbolic sine.
-  *
-  * \param[in]  M  a square matrix.
-  * \returns  expression representing \f$ \sinh(M) \f$
-  * 
-  * This function calls matrixFunction() with StdStemFunctions::sinh().
-  *
-  * \include MatrixSinh.cpp
-  * Output: \verbinclude MatrixSinh.out
-  */
 template <typename Derived>
 const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sinh() const
 {
@@ -652,17 +567,6 @@ const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::sinh() const
   return MatrixFunctionReturnValue<Derived>(derived(), StdStemFunctions<ComplexScalar>::sinh);
 }
 
-/** \ingroup MatrixFunctions_Module
-  *
-  * \brief Compute the matrix hyberbolic cosine.
-  *
-  * \param[in]  M  a square matrix.
-  * \returns  expression representing \f$ \cosh(M) \f$
-  * 
-  * This function calls matrixFunction() with StdStemFunctions::cosh().
-  *
-  * \sa ei_matrix_sinh() for an example.
-  */
 template <typename Derived>
 const MatrixFunctionReturnValue<Derived> MatrixBase<Derived>::cosh() const
 {