From 28a4c92cbff88c75b932ce0d091ccaa2b6010724 Mon Sep 17 00:00:00 2001 From: Christoph Hertzberg Date: Fri, 1 May 2015 22:10:41 +0200 Subject: bug #998: Started fixing doxygen warnings --- Eigen/src/Core/DenseBase.h | 5 ++--- Eigen/src/Core/MatrixBase.h | 2 -- Eigen/src/Core/SolveTriangular.h | 4 ++-- Eigen/src/Core/TriangularMatrix.h | 6 +++--- Eigen/src/SparseCore/SparseMatrix.h | 2 -- Eigen/src/SparseCore/SparseTriangularView.h | 7 ++++++- Eigen/src/SuperLUSupport/SuperLUSupport.h | 2 -- Eigen/src/UmfPackSupport/UmfPackSupport.h | 2 -- doc/A05_PortingFrom2To3.dox | 2 +- doc/B01_Experimental.dox | 6 +++--- doc/FixedSizeVectorizable.dox | 4 ++-- doc/StlContainers.dox | 4 ++-- doc/StructHavingEigenMembers.dox | 18 +++++++++--------- doc/UsingNVCC.dox | 2 +- doc/snippets/MatrixBase_extract.cpp | 13 ------------- doc/snippets/MatrixBase_marked.cpp | 14 -------------- doc/snippets/MatrixBase_part.cpp | 13 ------------- doc/snippets/MatrixBase_triangularView.cpp | 9 +++++++++ doc/snippets/Triangular_solve.cpp | 11 +++++++++++ 19 files changed, 51 insertions(+), 75 deletions(-) delete mode 100644 doc/snippets/MatrixBase_extract.cpp delete mode 100644 doc/snippets/MatrixBase_marked.cpp delete mode 100644 doc/snippets/MatrixBase_part.cpp create mode 100644 doc/snippets/MatrixBase_triangularView.cpp create mode 100644 doc/snippets/Triangular_solve.cpp 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 class DenseBase EIGEN_DEVICE_FUNC Derived& operator=(const ReturnByValue& 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 EIGEN_DEVICE_FUNC Derived& lazyAssign(const DenseBase& other); -#endif // not EIGEN_PARSED_BY_DOXYGEN EIGEN_DEVICE_FUNC CommaInitializer 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 class MatrixBase EIGEN_DEVICE_FUNC Derived& operator=(const ReturnByValue& other); -#ifndef EIGEN_PARSED_BY_DOXYGEN template EIGEN_DEVICE_FUNC Derived& lazyAssign(const ProductBase& other); -#endif // not EIGEN_PARSED_BY_DOXYGEN template 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::solveInPlace(const MatrixBase class TriangularBase : public EigenBase * \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::evalTo(MatrixBase &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 class TriangularViewImpl : public SparseMatrixBase > @@ -275,4 +278,6 @@ SparseMatrixBase::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 void _solve_impl(const MatrixBase &b, MatrixBase &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 > factorize_impl(); } - #ifndef EIGEN_PARSED_BY_DOXYGEN /** \internal */ template bool _solve_impl(const MatrixBase &b, MatrixBase &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, #include 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 as your allocator type. So for example, if you use std::vector, you need to do the following change (note that aligned_allocator is under namespace Eigen): +In Eigen2, \#include\ 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 as your allocator type. So for example, if you use std::vector, you need to do the following change (note that aligned_allocator is under namespace Eigen): 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, \endcode Note that the third parameter "std::less" 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 . 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: see this document. -\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 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 \ 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_extract.cpp b/doc/snippets/MatrixBase_extract.cpp deleted file mode 100644 index c96220f72..000000000 --- a/doc/snippets/MatrixBase_extract.cpp +++ /dev/null @@ -1,13 +0,0 @@ -#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() << endl; -cout << "Here is the strictly-upper-triangular matrix extracted from m:" << endl - << m.part() << endl; -cout << "Here is the unit-lower-triangular matrix extracted from m:" << endl - << m.part() << endl; -*/ \ No newline at end of file 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().setOnes(); -cout << "Here is the matrix m:" << endl << m << endl; -Matrix3d n = Matrix3d::Ones(); -n.part() *= 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().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().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() = (m*m.adjoint()).lazy(); -cout << "The result is:" << endl << n << endl; -*/ \ No newline at end of file diff --git a/doc/snippets/MatrixBase_triangularView.cpp b/doc/snippets/MatrixBase_triangularView.cpp new file mode 100644 index 000000000..03aa303f0 --- /dev/null +++ b/doc/snippets/MatrixBase_triangularView.cpp @@ -0,0 +1,9 @@ +Matrix3i m = Matrix3i::Random(); +cout << "Here is the matrix m:" << endl << m << endl; +cout << "Here is the upper-triangular matrix extracted from m:" << endl + << Matrix3i(m.triangularView()) << endl; +cout << "Here is the strictly-upper-triangular matrix extracted from m:" << endl + << Matrix3i(m.triangularView()) << endl; +cout << "Here is the unit-lower-triangular matrix extracted from m:" << endl + << Matrix3i(m.triangularView()) << 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().setOnes(); +cout << "Here is the matrix m:\n" << m << endl; +Matrix3d n = Matrix3d::Ones(); +n.triangularView() *= 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().solve(n) << endl; +cout << "And this is n*m.inverse():\n" + << m.triangularView().solve(n); -- cgit v1.2.3
Eigen 2Eigen 3