bug #998: Started fixing doxygen warnings

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);

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

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.

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
   */

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

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

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
     {

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;
 

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>

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

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).
 

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>.
 

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.
 

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)

doc/snippets/MatrixBase_marked.cpp

@@ -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);
-*/

doc/snippets/MatrixBase_part.cpp

@@ -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;
-*/

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;
-*/
+     << Matrix3i(m.triangularView<Eigen::UnitLower>()) << endl;
+// FIXME need to implement output for triangularViews (Bug 885)

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);