From 449ff74672dd07cc59f632e1bb53851baa814b1d Mon Sep 17 00:00:00 2001 From: Christoph Hertzberg Date: Fri, 19 Oct 2018 21:10:28 +0200 Subject: Fix most Doxygen warnings. Also add links to stable documentation from unsupported modules (by using the corresponding Doxytags file). Manually grafted from d107a371c61b764c73fd1570b1f3ed1c6400dd7e --- Eigen/src/Core/MatrixBase.h | 26 ++++++++++++++-------- doc/CMakeLists.txt | 4 ++-- doc/CoeffwiseMathFunctionsTable.dox | 5 +++-- doc/Doxyfile.in | 6 ++++- unsupported/Eigen/CXX11/src/Tensor/Tensor.h | 6 ++--- .../Eigen/CXX11/src/Tensor/TensorForcedEval.h | 6 ----- unsupported/Eigen/CXX11/src/Tensor/TensorMap.h | 12 +++++----- .../Eigen/CXX11/src/Tensor/TensorSyclTuple.h | 3 +++ .../src/TensorSymmetry/util/TemplateGroupTheory.h | 5 ++++- unsupported/Eigen/MatrixFunctions | 15 ++++++------- unsupported/Eigen/src/IterativeSolvers/GMRES.h | 2 +- .../Eigen/src/MatrixFunctions/MatrixFunction.h | 6 ++--- .../Eigen/src/MatrixFunctions/MatrixLogarithm.h | 2 +- .../Eigen/src/MatrixFunctions/MatrixPower.h | 12 +++++----- .../Eigen/src/Polynomials/PolynomialUtils.h | 8 +++---- .../Eigen/src/SparseExtra/BlockSparseMatrix.h | 2 +- 16 files changed, 67 insertions(+), 53 deletions(-) diff --git a/Eigen/src/Core/MatrixBase.h b/Eigen/src/Core/MatrixBase.h index 6046c8bae..596cdd133 100644 --- a/Eigen/src/Core/MatrixBase.h +++ b/Eigen/src/Core/MatrixBase.h @@ -456,16 +456,24 @@ template class MatrixBase ///////// MatrixFunctions module ///////// typedef typename internal::stem_function::type StemFunction; - const MatrixExponentialReturnValue exp() const; +#define EIGEN_MATRIX_FUNCTION(ReturnType, Name, Description) \ + /** \returns an expression of the matrix Description of \c *this. \brief This function requires the unsupported MatrixFunctions module. To compute the coefficient-wise Description use ArrayBase::##Name . */ \ + const ReturnType Name() const; +#define EIGEN_MATRIX_FUNCTION_1(ReturnType, Name, Description, Argument) \ + /** \returns an expression of the matrix Description of \c *this. \brief This function requires the unsupported MatrixFunctions module. To compute the coefficient-wise Description use ArrayBase::##Name . */ \ + const ReturnType Name(Argument) const; + + EIGEN_MATRIX_FUNCTION(MatrixExponentialReturnValue, exp, exponential) + /** \brief Helper function for the unsupported MatrixFunctions module.*/ const MatrixFunctionReturnValue matrixFunction(StemFunction f) const; - const MatrixFunctionReturnValue cosh() const; - const MatrixFunctionReturnValue sinh() const; - const MatrixFunctionReturnValue cos() const; - const MatrixFunctionReturnValue sin() const; - const MatrixSquareRootReturnValue sqrt() const; - const MatrixLogarithmReturnValue log() const; - const MatrixPowerReturnValue pow(const RealScalar& p) const; - const MatrixComplexPowerReturnValue pow(const std::complex& p) const; + EIGEN_MATRIX_FUNCTION(MatrixFunctionReturnValue, cosh, hyperbolic cosine) + EIGEN_MATRIX_FUNCTION(MatrixFunctionReturnValue, sinh, hyperbolic sine) + EIGEN_MATRIX_FUNCTION(MatrixFunctionReturnValue, cos, cosine) + EIGEN_MATRIX_FUNCTION(MatrixFunctionReturnValue, sin, sine) + EIGEN_MATRIX_FUNCTION(MatrixSquareRootReturnValue, sqrt, square root) + EIGEN_MATRIX_FUNCTION(MatrixLogarithmReturnValue, log, logarithm) + EIGEN_MATRIX_FUNCTION_1(MatrixPowerReturnValue, pow, power to \c p, const RealScalar& p) + EIGEN_MATRIX_FUNCTION_1(MatrixComplexPowerReturnValue, pow, power to \c p, const std::complex& p) protected: EIGEN_DEVICE_FUNC MatrixBase() : Base() {} diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 9f6730b9c..aa36d7891 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -37,8 +37,8 @@ set(EIGEN_DOXY_PROJECT_NAME "Eigen-unsupported") set(EIGEN_DOXY_OUTPUT_DIRECTORY_SUFFIX "/unsupported") set(EIGEN_DOXY_INPUT "\"${Eigen_SOURCE_DIR}/unsupported/Eigen\" \"${Eigen_SOURCE_DIR}/unsupported/doc\"") set(EIGEN_DOXY_HTML_COLORSTYLE_HUE "0") -# set(EIGEN_DOXY_TAGFILES "\"${Eigen_BINARY_DIR}/doc/eigen.doxytags =../\"") -set(EIGEN_DOXY_TAGFILES "") +set(EIGEN_DOXY_TAGFILES "\"${Eigen_BINARY_DIR}/doc/Eigen.doxytags=..\"") +#set(EIGEN_DOXY_TAGFILES "") configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in diff --git a/doc/CoeffwiseMathFunctionsTable.dox b/doc/CoeffwiseMathFunctionsTable.dox index c39a4bfab..12a565b16 100644 --- a/doc/CoeffwiseMathFunctionsTable.dox +++ b/doc/CoeffwiseMathFunctionsTable.dox @@ -63,7 +63,7 @@ This also means that, unless specified, if the function \c std::foo is available \anchor cwisetable_conj a.\link ArrayBase::conjugate conjugate\endlink(); \n \link Eigen::conj conj\endlink(a); \n - m.\link MatrixBase::conjugate conjugate(); + m.\link MatrixBase::conjugate conjugate\endlink(); complex conjugate (\f$ \bar{a_i} \f$),\n no-op for real @@ -133,8 +133,9 @@ This also means that, unless specified, if the function \c std::foo is available \anchor cwisetable_pow a.\link ArrayBase::pow pow\endlink(b); \n - \link Eigen::pow pow\endlink(a,b); + \link ArrayBase::pow(const Eigen::ArrayBase< Derived > &x, const Eigen::ArrayBase< ExponentDerived > &exponents) pow\endlink(a,b); + raises a number to the given power (\f$ a_i ^ {b_i} \f$) \n \c a and \c b can be either an array or scalar. using std::pow; \n diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 49b9fba39..3ebbeb812 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -1597,6 +1597,7 @@ PREDEFINED = EIGEN_EMPTY_STRUCT \ "EIGEN_CAT2(a,b)= a ## b"\ "EIGEN_CAT(a,b)=EIGEN_CAT2(a,b)"\ "EIGEN_CWISE_BINARY_RETURN_TYPE(LHS,RHS,OPNAME)=CwiseBinaryOp, const LHS, const RHS>"\ + "EIGEN_ALIGN_TO_BOUNDARY(x)="\ DOXCOMMA=, @@ -1619,6 +1620,9 @@ EXPAND_AS_DEFINED = EIGEN_MAKE_TYPEDEFS \ EIGEN_EULER_ANGLES_TYPEDEFS \ EIGEN_EULER_ANGLES_SINGLE_TYPEDEF \ EIGEN_EULER_SYSTEM_TYPEDEF \ + EIGEN_AUTODIFF_DECLARE_GLOBAL_UNARY \ + EIGEN_MATRIX_FUNCTION \ + EIGEN_MATRIX_FUNCTION_1 \ EIGEN_DOC_UNARY_ADDONS \ EIGEN_DOC_BLOCK_ADDONS_NOT_INNER_PANEL \ EIGEN_DOC_BLOCK_ADDONS_INNER_PANEL_IF @@ -1666,7 +1670,7 @@ ALLEXTERNALS = NO # in the modules index. If set to NO, only the current project's groups will # be listed. -EXTERNAL_GROUPS = YES +EXTERNAL_GROUPS = NO # The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of `which perl'). diff --git a/unsupported/Eigen/CXX11/src/Tensor/Tensor.h b/unsupported/Eigen/CXX11/src/Tensor/Tensor.h index 95349d0ed..17cee495f 100644 --- a/unsupported/Eigen/CXX11/src/Tensor/Tensor.h +++ b/unsupported/Eigen/CXX11/src/Tensor/Tensor.h @@ -23,12 +23,12 @@ namespace Eigen { * The %Tensor class encompasses only dynamic-size objects so far. * * The first two template parameters are required: - * \tparam Scalar_ \anchor tensor_tparam_scalar Numeric type, e.g. float, double, int or std::complex. + * \tparam Scalar_ Numeric type, e.g. float, double, int or `std::complex`. * User defined scalar types are supported as well (see \ref user_defined_scalars "here"). * \tparam NumIndices_ Number of indices (i.e. rank of the tensor) * * The remaining template parameters are optional -- in most cases you don't have to worry about them. - * \tparam Options_ \anchor tensor_tparam_options A combination of either \b #RowMajor or \b #ColMajor, and of either + * \tparam Options_ A combination of either \b #RowMajor or \b #ColMajor, and of either * \b #AutoAlign or \b #DontAlign. * The former controls \ref TopicStorageOrders "storage order", and defaults to column-major. The latter controls alignment, which is required * for vectorization. It defaults to aligning tensors. Note that tensors currently do not support any operations that profit from vectorization. @@ -42,7 +42,7 @@ namespace Eigen { * \endcode * * This class can be extended with the help of the plugin mechanism described on the page - * \ref TopicCustomizingEigen by defining the preprocessor symbol \c EIGEN_TENSOR_PLUGIN. + * \ref TopicCustomizing_Plugins by defining the preprocessor symbol \c EIGEN_TENSOR_PLUGIN. * * Some notes: * diff --git a/unsupported/Eigen/CXX11/src/Tensor/TensorForcedEval.h b/unsupported/Eigen/CXX11/src/Tensor/TensorForcedEval.h index edf9f85d8..78068be35 100644 --- a/unsupported/Eigen/CXX11/src/Tensor/TensorForcedEval.h +++ b/unsupported/Eigen/CXX11/src/Tensor/TensorForcedEval.h @@ -19,12 +19,6 @@ namespace Eigen { * * */ -/// template class MakePointer_ is added to convert the host pointer to the device pointer. -/// It is added due to the fact that for our device compiler T* is not allowed. -/// If we wanted to use the same Evaluator functions we have to convert that type to our pointer T. -/// This is done through our MakePointer_ class. By default the Type in the MakePointer_ is T* . -/// Therefore, by adding the default value, we managed to convert the type and it does not break any -/// existing code as its default value is T*. namespace internal { template struct traits > diff --git a/unsupported/Eigen/CXX11/src/Tensor/TensorMap.h b/unsupported/Eigen/CXX11/src/Tensor/TensorMap.h index d1cc0593f..28f629080 100644 --- a/unsupported/Eigen/CXX11/src/Tensor/TensorMap.h +++ b/unsupported/Eigen/CXX11/src/Tensor/TensorMap.h @@ -12,18 +12,20 @@ namespace Eigen { +// FIXME use proper doxygen documentation (e.g. \tparam MakePointer_) + /** \class TensorMap * \ingroup CXX11_Tensor_Module * * \brief A tensor expression mapping an existing array of data. * */ -/// template class MakePointer_ is added to convert the host pointer to the device pointer. -/// It is added due to the fact that for our device compiler T* is not allowed. -/// If we wanted to use the same Evaluator functions we have to convert that type to our pointer T. -/// This is done through our MakePointer_ class. By default the Type in the MakePointer_ is T* . +/// `template class MakePointer_` is added to convert the host pointer to the device pointer. +/// It is added due to the fact that for our device compiler `T*` is not allowed. +/// If we wanted to use the same Evaluator functions we have to convert that type to our pointer `T`. +/// This is done through our `MakePointer_` class. By default the Type in the `MakePointer_` is `T*` . /// Therefore, by adding the default value, we managed to convert the type and it does not break any -/// existing code as its default value is T*. +/// existing code as its default value is `T*`. template class MakePointer_> class TensorMap : public TensorBase > { public: diff --git a/unsupported/Eigen/CXX11/src/Tensor/TensorSyclTuple.h b/unsupported/Eigen/CXX11/src/Tensor/TensorSyclTuple.h index 461fe8173..5385c7eac 100644 --- a/unsupported/Eigen/CXX11/src/Tensor/TensorSyclTuple.h +++ b/unsupported/Eigen/CXX11/src/Tensor/TensorSyclTuple.h @@ -148,6 +148,8 @@ struct IndexList {}; template struct RangeBuilder; +// FIXME Doxygen has problems with recursive inheritance +#ifndef EIGEN_PARSED_BY_DOXYGEN /// \brief base Step: Specialisation of the \ref RangeBuilder when the /// MIN==MAX. In this case the Is... is [0 to sizeof...(tuple elements)) /// \tparam MIN is the starting index of the tuple @@ -165,6 +167,7 @@ struct RangeBuilder { /// \tparam Is... are the list of generated index so far template struct RangeBuilder : public RangeBuilder {}; +#endif // EIGEN_PARSED_BY_DOXYGEN /// \brief IndexRange that returns a [MIN, MAX) index range /// \tparam MIN is the starting index in the tuple diff --git a/unsupported/Eigen/CXX11/src/TensorSymmetry/util/TemplateGroupTheory.h b/unsupported/Eigen/CXX11/src/TensorSymmetry/util/TemplateGroupTheory.h index 62bede101..54bf9dbb3 100644 --- a/unsupported/Eigen/CXX11/src/TensorSymmetry/util/TemplateGroupTheory.h +++ b/unsupported/Eigen/CXX11/src/TensorSymmetry/util/TemplateGroupTheory.h @@ -167,7 +167,9 @@ template< typename elements, bool dont_add_current_element // = false > -struct dimino_first_step_elements_helper : +struct dimino_first_step_elements_helper +#ifndef EIGEN_PARSED_BY_DOXYGEN + : // recursive inheritance is too difficult for Doxygen public dimino_first_step_elements_helper< Multiply, Equality, @@ -187,6 +189,7 @@ template< typename elements > struct dimino_first_step_elements_helper +#endif // EIGEN_PARSED_BY_DOXYGEN { typedef elements type; constexpr static int global_flags = Equality::global_flags; diff --git a/unsupported/Eigen/MatrixFunctions b/unsupported/Eigen/MatrixFunctions index 06acde68d..20c23d1c5 100644 --- a/unsupported/Eigen/MatrixFunctions +++ b/unsupported/Eigen/MatrixFunctions @@ -165,8 +165,8 @@ the z-axis. \include MatrixExponential.cpp Output: \verbinclude MatrixExponential.out -\note \p M has to be a matrix of \c float, \c double, \c long double -\c complex, \c complex, or \c complex . +\note \p M has to be a matrix of \c float, \c double, `long double` +\c complex, \c complex, or `complex` . \subsection matrixbase_log MatrixBase::log() @@ -223,9 +223,8 @@ documentation of \ref matrixbase_exp "exp()". \include MatrixLogarithm.cpp Output: \verbinclude MatrixLogarithm.out -\note \p M has to be a matrix of \c float, \c double, long -double, \c complex, \c complex, or \c complex . +\note \p M has to be a matrix of \c float, \c double, `long +double`, \c complex, \c complex, or `complex`. \sa MatrixBase::exp(), MatrixBase::matrixFunction(), class MatrixLogarithmAtomic, MatrixBase::sqrt(). @@ -330,9 +329,9 @@ Example: \include MatrixPower_optimal.cpp Output: \verbinclude MatrixPower_optimal.out -\note \p M has to be a matrix of \c float, \c double, long -double, \c complex, \c complex, or \c complex . +\note \p M has to be a matrix of \c float, \c double, `long +double`, \c complex, \c complex, or +\c complex . \sa MatrixBase::exp(), MatrixBase::log(), class MatrixPower. diff --git a/unsupported/Eigen/src/IterativeSolvers/GMRES.h b/unsupported/Eigen/src/IterativeSolvers/GMRES.h index 8b7cedf2a..ff912094f 100644 --- a/unsupported/Eigen/src/IterativeSolvers/GMRES.h +++ b/unsupported/Eigen/src/IterativeSolvers/GMRES.h @@ -21,7 +21,7 @@ namespace internal { * * Parameters: * \param mat matrix of linear system of equations -* \param Rhs right hand side vector of linear system of equations +* \param rhs right hand side vector of linear system of equations * \param x on input: initial guess, on output: solution * \param precond preconditioner used * \param iters on input: maximum number of iterations to perform diff --git a/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h b/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h index 133d78625..46f2720d0 100644 --- a/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h +++ b/unsupported/Eigen/src/MatrixFunctions/MatrixFunction.h @@ -7,8 +7,8 @@ // Public License v. 2.0. If a copy of the MPL was not distributed // with this file, You can obtain one at http://mozilla.org/MPL/2.0/. -#ifndef EIGEN_MATRIX_FUNCTION -#define EIGEN_MATRIX_FUNCTION +#ifndef EIGEN_MATRIX_FUNCTION_H +#define EIGEN_MATRIX_FUNCTION_H #include "StemFunction.h" @@ -566,4 +566,4 @@ const MatrixFunctionReturnValue MatrixBase::cosh() const } // end namespace Eigen -#endif // EIGEN_MATRIX_FUNCTION +#endif // EIGEN_MATRIX_FUNCTION_H diff --git a/unsupported/Eigen/src/MatrixFunctions/MatrixLogarithm.h b/unsupported/Eigen/src/MatrixFunctions/MatrixLogarithm.h index a8d879a12..79f3f957c 100644 --- a/unsupported/Eigen/src/MatrixFunctions/MatrixLogarithm.h +++ b/unsupported/Eigen/src/MatrixFunctions/MatrixLogarithm.h @@ -324,7 +324,7 @@ public: /** \brief Compute the matrix logarithm. * - * \param[out] result Logarithm of \p A, where \A is as specified in the constructor. + * \param[out] result Logarithm of \c A, where \c A is as specified in the constructor. */ template inline void evalTo(ResultType& result) const diff --git a/unsupported/Eigen/src/MatrixFunctions/MatrixPower.h b/unsupported/Eigen/src/MatrixFunctions/MatrixPower.h index 1ceb5cf39..95f6fbca8 100644 --- a/unsupported/Eigen/src/MatrixFunctions/MatrixPower.h +++ b/unsupported/Eigen/src/MatrixFunctions/MatrixPower.h @@ -56,8 +56,8 @@ class MatrixPowerParenthesesReturnValue : public ReturnByValue< MatrixPowerParen * \param[out] result */ template - inline void evalTo(ResultType& res) const - { m_pow.compute(res, m_p); } + inline void evalTo(ResultType& result) const + { m_pow.compute(result, m_p); } Index rows() const { return m_pow.rows(); } Index cols() const { return m_pow.cols(); } @@ -614,8 +614,8 @@ class MatrixPowerReturnValue : public ReturnByValue< MatrixPowerReturnValue - inline void evalTo(ResultType& res) const - { MatrixPower(m_A.eval()).compute(res, m_p); } + inline void evalTo(ResultType& result) const + { MatrixPower(m_A.eval()).compute(result, m_p); } Index rows() const { return m_A.rows(); } Index cols() const { return m_A.cols(); } @@ -664,8 +664,8 @@ class MatrixComplexPowerReturnValue : public ReturnByValue< MatrixComplexPowerRe * constructor. */ template - inline void evalTo(ResultType& res) const - { res = (m_p * m_A.log()).exp(); } + inline void evalTo(ResultType& result) const + { result = (m_p * m_A.log()).exp(); } Index rows() const { return m_A.rows(); } Index cols() const { return m_A.cols(); } diff --git a/unsupported/Eigen/src/Polynomials/PolynomialUtils.h b/unsupported/Eigen/src/Polynomials/PolynomialUtils.h index 40ba65b7e..394e857ac 100644 --- a/unsupported/Eigen/src/Polynomials/PolynomialUtils.h +++ b/unsupported/Eigen/src/Polynomials/PolynomialUtils.h @@ -20,8 +20,8 @@ namespace Eigen { * e.g. \f$ 1 + 3x^2 \f$ is stored as a vector \f$ [ 1, 0, 3 ] \f$. * \param[in] x : the value to evaluate the polynomial at. * - * Note for stability: - *
\f$ |x| \le 1 \f$
+ * \note for stability: + * \f$ |x| \le 1 \f$ */ template inline @@ -67,8 +67,8 @@ T poly_eval( const Polynomials& poly, const T& x ) * by degrees i.e. poly[i] is the coefficient of degree i of the polynomial * e.g. \f$ 1 + 3x^2 \f$ is stored as a vector \f$ [ 1, 0, 3 ] \f$. * - * Precondition: - *
the leading coefficient of the input polynomial poly must be non zero
+ * \pre + * the leading coefficient of the input polynomial poly must be non zero */ template inline diff --git a/unsupported/Eigen/src/SparseExtra/BlockSparseMatrix.h b/unsupported/Eigen/src/SparseExtra/BlockSparseMatrix.h index 0e8350a7d..536a0c320 100644 --- a/unsupported/Eigen/src/SparseExtra/BlockSparseMatrix.h +++ b/unsupported/Eigen/src/SparseExtra/BlockSparseMatrix.h @@ -931,7 +931,7 @@ class BlockSparseMatrix : public SparseMatrixBase in the array of values + * \returns the starting position of the block \p id in the array of values */ Index blockPtr(Index id) const { -- cgit v1.2.3