bug #998: Started fixing doxygen warnings

18 files changed, 46 insertions, 70 deletions

diff --git a/Eigen/src/Core/DenseBase.h b/Eigen/src/Core/DenseBase.h
index 51540aba5..4e66e956f 100644
--- a/Eigen/src/Core/DenseBase.h
+++ b/Eigen/src/Core/DenseBase.h
@@ -276,13 +276,12 @@ template<typename Derived> class DenseBase
     EIGEN_DEVICE_FUNC
     Derived& operator=(const ReturnByValue<OtherDerived>& func);
 
-#ifndef EIGEN_PARSED_BY_DOXYGEN
-    /** Copies \a other into *this without evaluating other. \returns a reference to *this.
+    /** \ínternal
+      * Copies \a other into *this without evaluating other. \returns a reference to *this.
       * \deprecated */
     template<typename OtherDerived>
     EIGEN_DEVICE_FUNC
     Derived& lazyAssign(const DenseBase<OtherDerived>& other);
-#endif // not EIGEN_PARSED_BY_DOXYGEN
 
     EIGEN_DEVICE_FUNC
     CommaInitializer<Derived> operator<< (const Scalar& s);
diff --git a/Eigen/src/Core/MatrixBase.h b/Eigen/src/Core/MatrixBase.h
index ed28b4d07..5482b237e 100644
--- a/Eigen/src/Core/MatrixBase.h
+++ b/Eigen/src/Core/MatrixBase.h
@@ -164,11 +164,9 @@ template<typename Derived> class MatrixBase
     EIGEN_DEVICE_FUNC
     Derived& operator=(const ReturnByValue<OtherDerived>& other);
 
-#ifndef EIGEN_PARSED_BY_DOXYGEN
     template<typename ProductDerived, typename Lhs, typename Rhs>
     EIGEN_DEVICE_FUNC
     Derived& lazyAssign(const ProductBase<ProductDerived, Lhs,Rhs>& other);
-#endif // not EIGEN_PARSED_BY_DOXYGEN
 
     template<typename OtherDerived>
     EIGEN_DEVICE_FUNC
diff --git a/Eigen/src/Core/SolveTriangular.h b/Eigen/src/Core/SolveTriangular.h
index 9bac726f7..ded42e0e8 100644
--- a/Eigen/src/Core/SolveTriangular.h
+++ b/Eigen/src/Core/SolveTriangular.h
@@ -198,8 +198,8 @@ void TriangularViewImpl<MatrixType,Mode,Dense>::solveInPlace(const MatrixBase<Ot
   * diagonal must be non zero). It works as a forward (resp. backward) substitution if \c *this
   * is an upper (resp. lower) triangular matrix.
   *
-  * Example: \include MatrixBase_marked.cpp
-  * Output: \verbinclude MatrixBase_marked.out
+  * Example: \include Triangular_solve.cpp
+  * Output: \verbinclude Triangular_solve.out
   *
   * This function returns an expression of the inverse-multiply and can works in-place if it is assigned
   * to the same matrix or vector \a other.
diff --git a/Eigen/src/Core/TriangularMatrix.h b/Eigen/src/Core/TriangularMatrix.h
index fd53ae4cb..7b3be2120 100644
--- a/Eigen/src/Core/TriangularMatrix.h
+++ b/Eigen/src/Core/TriangularMatrix.h
@@ -154,7 +154,7 @@ template<typename Derived> class TriangularBase : public EigenBase<Derived>
   * \param Mode the kind of triangular matrix expression to construct. Can be #Upper,
   *             #Lower, #UnitUpper, #UnitLower, #StrictlyUpper, or #StrictlyLower.
   *             This is in fact a bit field; it must have either #Upper or #Lower, 
-  *             and additionnaly it may have #UnitDiag or #ZeroDiag or neither.
+  *             and additionally it may have #UnitDiag or #ZeroDiag or neither.
   *
   * This class represents a triangular part of a matrix, not necessarily square. Strictly speaking, for rectangular
   * matrices one should speak of "trapezoid" parts. This class is the return type
@@ -549,8 +549,8 @@ void TriangularBase<Derived>::evalTo(MatrixBase<DenseDerived> &other) const
   * The parameter \a Mode can have the following values: \c #Upper, \c #StrictlyUpper, \c #UnitUpper,
   * \c #Lower, \c #StrictlyLower, \c #UnitLower.
   *
-  * Example: \include MatrixBase_extract.cpp
-  * Output: \verbinclude MatrixBase_extract.out
+  * Example: \include MatrixBase_triangularView.cpp
+  * Output: \verbinclude MatrixBase_triangularView.out
   *
   * \sa class TriangularView
   */
diff --git a/Eigen/src/SparseCore/SparseMatrix.h b/Eigen/src/SparseCore/SparseMatrix.h
index 228d873c7..5c5bf2d8c 100644
--- a/Eigen/src/SparseCore/SparseMatrix.h
+++ b/Eigen/src/SparseCore/SparseMatrix.h
@@ -792,10 +792,8 @@ class SparseMatrix
       std::free(m_innerNonZeros);
     }
 
-#ifndef EIGEN_PARSED_BY_DOXYGEN
     /** Overloaded for performance */
     Scalar sum() const;
-#endif
     
 #   ifdef EIGEN_SPARSEMATRIX_PLUGIN
 #     include EIGEN_SPARSEMATRIX_PLUGIN
diff --git a/Eigen/src/SparseCore/SparseTriangularView.h b/Eigen/src/SparseCore/SparseTriangularView.h
index 34ec07a13..7695f299e 100644
--- a/Eigen/src/SparseCore/SparseTriangularView.h
+++ b/Eigen/src/SparseCore/SparseTriangularView.h
@@ -11,7 +11,10 @@
 #ifndef EIGEN_SPARSE_TRIANGULARVIEW_H
 #define EIGEN_SPARSE_TRIANGULARVIEW_H
 
-namespace Eigen { 
+#ifndef EIGEN_PARSED_BY_DOXYGEN
+// Doxygen gets confused with template specialization:
+// https://bugzilla.gnome.org/show_bug.cgi?id=406027
+namespace Eigen {
 
 template<typename MatrixType, unsigned int Mode> class TriangularViewImpl<MatrixType,Mode,Sparse>
   : public SparseMatrixBase<TriangularView<MatrixType,Mode> >
@@ -275,4 +278,6 @@ SparseMatrixBase<Derived>::triangularView() const
 
 } // end namespace Eigen
 
+#endif // not EIGEN_PARSED_BY_DOXYGEN
+
 #endif // EIGEN_SPARSE_TRIANGULARVIEW_H
diff --git a/Eigen/src/SuperLUSupport/SuperLUSupport.h b/Eigen/src/SuperLUSupport/SuperLUSupport.h
index 1bbd2758e..d067d8fdf 100644
--- a/Eigen/src/SuperLUSupport/SuperLUSupport.h
+++ b/Eigen/src/SuperLUSupport/SuperLUSupport.h
@@ -503,11 +503,9 @@ class SuperLU : public SuperLUBase<_MatrixType,SuperLU<_MatrixType> >
       */
     void factorize(const MatrixType& matrix);
     
-    #ifndef EIGEN_PARSED_BY_DOXYGEN
     /** \internal */
     template<typename Rhs,typename Dest>
     void _solve_impl(const MatrixBase<Rhs> &b, MatrixBase<Dest> &dest) const;
-    #endif // EIGEN_PARSED_BY_DOXYGEN
     
     inline const LMatrixType& matrixL() const
     {
diff --git a/Eigen/src/UmfPackSupport/UmfPackSupport.h b/Eigen/src/UmfPackSupport/UmfPackSupport.h
index 3d30403c7..f3a6e7c0e 100644
--- a/Eigen/src/UmfPackSupport/UmfPackSupport.h
+++ b/Eigen/src/UmfPackSupport/UmfPackSupport.h
@@ -251,11 +251,9 @@ class UmfPackLU : public SparseSolverBase<UmfPackLU<_MatrixType> >
       factorize_impl();
     }
 
-    #ifndef EIGEN_PARSED_BY_DOXYGEN
     /** \internal */
     template<typename BDerived,typename XDerived>
     bool _solve_impl(const MatrixBase<BDerived> &b, MatrixBase<XDerived> &x) const;
-    #endif
 
     Scalar determinant() const;
 
diff --git a/doc/A05_PortingFrom2To3.dox b/doc/A05_PortingFrom2To3.dox
index 47011aec0..2d9182bbb 100644
--- a/doc/A05_PortingFrom2To3.dox
+++ b/doc/A05_PortingFrom2To3.dox
@@ -278,7 +278,7 @@ result = Vector4f::MapAligned(some_aligned_array);
 
 \section StdContainers STL Containers
 
-In Eigen2, <tt>#include<Eigen/StdVector></tt> tweaked std::vector to automatically align elements. The problem was that that was quite invasive. In Eigen3, we only override standard behavior if you use Eigen::aligned_allocator<T> as your allocator type. So for example, if you use std::vector<Matrix4f>, you need to do the following change (note that aligned_allocator is under namespace Eigen):
+In Eigen2, <tt>\#include\<Eigen/StdVector\></tt> tweaked std::vector to automatically align elements. The problem was that that was quite invasive. In Eigen3, we only override standard behavior if you use Eigen::aligned_allocator<T> as your allocator type. So for example, if you use std::vector<Matrix4f>, you need to do the following change (note that aligned_allocator is under namespace Eigen):
 
 <table class="manual">
 <tr><th>Eigen 2</th><th>Eigen 3</th></tr>
diff --git a/doc/B01_Experimental.dox b/doc/B01_Experimental.dox
index 5fc0ccd60..e1f031db8 100644
--- a/doc/B01_Experimental.dox
+++ b/doc/B01_Experimental.dox
@@ -4,7 +4,7 @@ namespace Eigen {
 
 \eigenAutoToc
 
-\section summary Summary
+\section Experimental_summary Summary
 
 With the 2.0 release, Eigen's API is, to a large extent, stable. However, we wish to retain the freedom to make API incompatible changes. To that effect, we call many parts of Eigen "experimental" which means that they are not subject to API stability guarantee.
 
@@ -17,7 +17,7 @@ Experimental features may at any time:
 \li be subject to an API incompatible change;
 \li introduce API or ABI incompatible changes in your own code if you let them affect your API or ABI.
 
-\section modules Experimental modules
+\section Experimental_modules Experimental modules
 
 The following modules are considered entirely experimental, and we make no firm API stability guarantee about them for the time being:
 \li SVD
@@ -26,7 +26,7 @@ The following modules are considered entirely experimental, and we make no firm
 \li Sparse
 \li Geometry (this one should be mostly stable, but it's a little too early to make a formal guarantee)
 
-\section core Experimental parts of the Core module
+\section Experimental_core Experimental parts of the Core module
 
 In the Core module, the only classes subject to ABI stability guarantee (meaning that you can use it for data members in your public ABI) is:
 \li Matrix
diff --git a/doc/FixedSizeVectorizable.dox b/doc/FixedSizeVectorizable.dox
index 8ae135173..49e38af76 100644
--- a/doc/FixedSizeVectorizable.dox
+++ b/doc/FixedSizeVectorizable.dox
@@ -4,7 +4,7 @@ namespace Eigen {
 
 The goal of this page is to explain what we mean by "fixed-size vectorizable".
 
-\section summary Executive Summary
+\section FixedSizeVectorizable_summary Executive Summary
 
 An Eigen object is called "fixed-size vectorizable" if it has fixed size and that size is a multiple of 16 bytes.
 
@@ -21,7 +21,7 @@ Examples include:
 \li Eigen::Quaterniond
 \li Eigen::Quaternionf
 
-\section explanation Explanation
+\section FixedSizeVectorizable_explanation Explanation
 
 First, "fixed-size" should be clear: an Eigen object has fixed size if its number of rows and its number of columns are fixed at compile-time. So for example Matrix3f has fixed size, but MatrixXf doesn't (the opposite of fixed-size is dynamic-size).
 
diff --git a/doc/StlContainers.dox b/doc/StlContainers.dox
index d8d0d529c..e0f8714a9 100644
--- a/doc/StlContainers.dox
+++ b/doc/StlContainers.dox
@@ -4,7 +4,7 @@ namespace Eigen {
 
 \eigenAutoToc
 
-\section summary Executive summary
+\section StlContainers_summary Executive summary
 
 Using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", or classes having members of such types, requires taking the following two steps:
 
@@ -28,7 +28,7 @@ std::map<int, Eigen::Vector4f, std::less<int>,
 \endcode
 Note that the third parameter "std::less<int>" is just the default value, but we have to include it because we want to specify the fourth parameter, which is the allocator type.
 
-\section vector The case of std::vector
+\section StlContainers_vector The case of std::vector
 
 The situation with std::vector was even worse (explanation below) so we had to specialize it for the Eigen::aligned_allocator type. In practice you \b must use the Eigen::aligned_allocator (not another aligned allocator), \b and \#include <Eigen/StdVector>.
 
diff --git a/doc/StructHavingEigenMembers.dox b/doc/StructHavingEigenMembers.dox
index 74a8d5217..bd4fa7599 100644
--- a/doc/StructHavingEigenMembers.dox
+++ b/doc/StructHavingEigenMembers.dox
@@ -4,11 +4,11 @@ namespace Eigen {
 
 \eigenAutoToc
 
-\section summary Executive Summary
+\section StructHavingEigenMembers_summary Executive Summary
 
 If you define a structure having members of \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you must overload its "operator new" so that it generates 16-bytes-aligned pointers. Fortunately, Eigen provides you with a macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW that does that for you.
 
-\section what What kind of code needs to be changed?
+\section StructHavingEigenMembers_what What kind of code needs to be changed?
 
 The kind of code that needs to be changed is this:
 
@@ -27,7 +27,7 @@ Foo *foo = new Foo;
 
 In other words: you have a class that has as a member a \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen object", and then you dynamically create an object of that class.
 
-\section how How should such code be modified?
+\section StructHavingEigenMembers_how How should such code be modified?
 
 Very easy, you just need to put a EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro in a public part of your class, like this:
 
@@ -50,7 +50,7 @@ This macro makes "new Foo" always return an aligned pointer.
 
 If this approach is too intrusive, see also the \ref othersolutions.
 
-\section why Why is this needed?
+\section StructHavingEigenMembers_why Why is this needed?
 
 OK let's say that your code looks like this:
 
@@ -81,7 +81,7 @@ The alignment attribute of the member v is then relative to the start of the cla
 
 The solution is to let class Foo have an aligned "operator new", as we showed in the previous section.
 
-\section movetotop Should I then put all the members of Eigen types at the beginning of my class?
+\section StructHavingEigenMembers_movetotop Should I then put all the members of Eigen types at the beginning of my class?
 
 That's not required. Since Eigen takes care of declaring 128-bit alignment, all members that need it are automatically 128-bit aligned relatively to the class. So code like this works fine:
 
@@ -95,15 +95,15 @@ public:
 };
 \endcode
 
-\section dynamicsize What about dynamic-size matrices and vectors?
+\section StructHavingEigenMembers_dynamicsize What about dynamic-size matrices and vectors?
 
 Dynamic-size matrices and vectors, such as Eigen::VectorXd, allocate dynamically their own array of coefficients, so they take care of requiring absolute alignment automatically. So they don't cause this issue. The issue discussed here is only with \ref TopicFixedSizeVectorizable  "fixed-size vectorizable matrices and vectors".
 
-\section bugineigen So is this a bug in Eigen?
+\section StructHavingEigenMembers_bugineigen So is this a bug in Eigen?
 
 No, it's not our bug. It's more like an inherent problem of the C++98 language specification, and seems to be taken care of in the upcoming language revision: <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf">see this document</a>.
 
-\section conditional What if I want to do this conditionnally (depending on template parameters) ?
+\section StructHavingEigenMembers_conditional What if I want to do this conditionnally (depending on template parameters) ?
 
 For this situation, we offer the macro EIGEN_MAKE_ALIGNED_OPERATOR_NEW_IF(NeedsToAlign). It will generate aligned operators like EIGEN_MAKE_ALIGNED_OPERATOR_NEW if NeedsToAlign is true. It will generate operators with the default alignment if NeedsToAlign is false.
 
@@ -128,7 +128,7 @@ Foo<3> *foo3 = new Foo<3>; // foo3 has only the system default alignment guarant
 \endcode
 
 
-\section othersolutions Other solutions
+\section StructHavingEigenMembers_othersolutions Other solutions
 
 In case putting the EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro everywhere is too intrusive, there exists at least two other solutions.
 
diff --git a/doc/UsingNVCC.dox b/doc/UsingNVCC.dox
index e9df5de04..f8e755b79 100644
--- a/doc/UsingNVCC.dox
+++ b/doc/UsingNVCC.dox
@@ -15,7 +15,7 @@ Known issues:
  
  - \c nvcc with \c clang does not work (patch welcome)
  
- - \c nvcc 5.5 with gcc-4.7 (or greater) has issues with the standard \c <limits> header file. To workaround this, you can add the following before including any other files:
+ - \c nvcc 5.5 with gcc-4.7 (or greater) has issues with the standard \c \<limits\> header file. To workaround this, you can add the following before including any other files:
    \code
     // workaround issue between gcc >= 4.7 and cuda 5.5
     #if (defined __GNUC__) && (__GNUC__>4 || __GNUC_MINOR__>=7)
diff --git a/doc/snippets/MatrixBase_marked.cpp b/doc/snippets/MatrixBase_marked.cpp
deleted file mode 100644
index f60712178..000000000
--- a/doc/snippets/MatrixBase_marked.cpp
+++ /dev/null
@@ -1,14 +0,0 @@
-#ifndef _MSC_VER
-  #warning deprecated
-#endif
-/*
-Matrix3d m = Matrix3d::Zero();
-m.part<Eigen::UpperTriangular>().setOnes();
-cout << "Here is the matrix m:" << endl << m << endl;
-Matrix3d n = Matrix3d::Ones();
-n.part<Eigen::LowerTriangular>() *= 2;
-cout << "Here is the matrix n:" << endl << n << endl;
-cout << "And now here is m.inverse()*n, taking advantage of the fact that"
-        " m is upper-triangular:" << endl
-     << m.marked<Eigen::UpperTriangular>().solveTriangular(n);
-*/
\ No newline at end of file
diff --git a/doc/snippets/MatrixBase_part.cpp b/doc/snippets/MatrixBase_part.cpp
deleted file mode 100644
index d3e7f482e..000000000
--- a/doc/snippets/MatrixBase_part.cpp
+++ /dev/null
@@ -1,13 +0,0 @@
-#ifndef _MSC_VER
-  #warning deprecated
-#endif
-/*
-Matrix3d m = Matrix3d::Zero();
-m.part<Eigen::StrictlyUpperTriangular>().setOnes();
-cout << "Here is the matrix m:" << endl << m << endl;
-cout << "And let us now compute m*m.adjoint() in a very optimized way" << endl
-     << "taking advantage of the symmetry." << endl;
-Matrix3d n;
-n.part<Eigen::SelfAdjoint>() = (m*m.adjoint()).lazy();
-cout << "The result is:" << endl << n << endl;
-*/
\ No newline at end of file
diff --git a/doc/snippets/MatrixBase_extract.cpp b/doc/snippets/MatrixBase_triangularView.cpp
index c96220f72..03aa303f0 100644
--- a/doc/snippets/MatrixBase_extract.cpp
+++ b/doc/snippets/MatrixBase_triangularView.cpp
@@ -1,13 +1,9 @@
-#ifndef _MSC_VER
-  #warning deprecated
-#endif
-/* deprecated
 Matrix3i m = Matrix3i::Random();
 cout << "Here is the matrix m:" << endl << m << endl;
 cout << "Here is the upper-triangular matrix extracted from m:" << endl
-     << m.part<Eigen::UpperTriangular>() << endl;
+     << Matrix3i(m.triangularView<Eigen::Upper>()) << endl;
 cout << "Here is the strictly-upper-triangular matrix extracted from m:" << endl
-     << m.part<Eigen::StrictlyUpperTriangular>() << endl;
+     << Matrix3i(m.triangularView<Eigen::StrictlyUpper>()) << endl;
 cout << "Here is the unit-lower-triangular matrix extracted from m:" << endl
-     << m.part<Eigen::UnitLowerTriangular>() << endl;
-*/
\ No newline at end of file
+     << Matrix3i(m.triangularView<Eigen::UnitLower>()) << endl;
+// FIXME need to implement output for triangularViews (Bug 885)
diff --git a/doc/snippets/Triangular_solve.cpp b/doc/snippets/Triangular_solve.cpp
new file mode 100644
index 000000000..548442467
--- /dev/null
+++ b/doc/snippets/Triangular_solve.cpp
@@ -0,0 +1,11 @@
+Matrix3d m = Matrix3d::Zero();
+m.triangularView<Eigen::Upper>().setOnes();
+cout << "Here is the matrix m:\n" << m << endl;
+Matrix3d n = Matrix3d::Ones();
+n.triangularView<Eigen::Lower>() *= 2;
+cout << "Here is the matrix n:\n" << n << endl;
+cout << "And now here is m.inverse()*n, taking advantage of the fact that"
+        " m is upper-triangular:\n"
+     << m.triangularView<Eigen::Upper>().solve(n) << endl;
+cout << "And this is n*m.inverse():\n"
+     << m.triangularView<Eigen::Upper>().solve<Eigen::OnTheRight>(n);