From 9466e5f94edbff1219cd48639fd0ef80e11b85a9 Mon Sep 17 00:00:00 2001 From: Benoit Jacob Date: Tue, 19 Aug 2008 04:30:28 +0000 Subject: * doc improvements in Cwise and PartialRedux: - 33 new snippets - unfuck doxygen output in Cwise (issues with function macros) - more see-also links from outside, making Cwise more discoverable * rename matrixNorm() to operatorNorm(). There are many matrix norms (the L2 is another one) but only one is called the operator norm. Risk of confusion with keyword operator is not too scary after all. --- Eigen/src/Array/CwiseOperators.h | 149 +++++++++++++++++++++++++++++++++------ Eigen/src/Array/PartialRedux.h | 35 ++++++++- 2 files changed, 160 insertions(+), 24 deletions(-) (limited to 'Eigen/src/Array') diff --git a/Eigen/src/Array/CwiseOperators.h b/Eigen/src/Array/CwiseOperators.h index 0dd7bb01c..498bc86f2 100644 --- a/Eigen/src/Array/CwiseOperators.h +++ b/Eigen/src/Array/CwiseOperators.h @@ -29,7 +29,13 @@ /** \array_module * - * \returns an expression of the coefficient-wise square root of *this. */ + * \returns an expression of the coefficient-wise square root of *this. + * + * Example: \include Cwise_sqrt.cpp + * Output: \verbinclude Cwise_sqrt.out + * + * \sa pow(), square() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_sqrt_op) Cwise::sqrt() const @@ -39,7 +45,13 @@ Cwise::sqrt() const /** \array_module * - * \returns an expression of the coefficient-wise exponential of *this. */ + * \returns an expression of the coefficient-wise exponential of *this. + * + * Example: \include Cwise_exp.cpp + * Output: \verbinclude Cwise_exp.out + * + * \sa pow(), log(), sin(), cos() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_exp_op) Cwise::exp() const @@ -49,7 +61,13 @@ Cwise::exp() const /** \array_module * - * \returns an expression of the coefficient-wise logarithm of *this. */ + * \returns an expression of the coefficient-wise logarithm of *this. + * + * Example: \include Cwise_log.cpp + * Output: \verbinclude Cwise_log.out + * + * \sa exp() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_log_op) Cwise::log() const @@ -59,7 +77,13 @@ Cwise::log() const /** \array_module * - * \returns an expression of the coefficient-wise cosine of *this. */ + * \returns an expression of the coefficient-wise cosine of *this. + * + * Example: \include Cwise_cos.cpp + * Output: \verbinclude Cwise_cos.out + * + * \sa sin(), exp() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_cos_op) Cwise::cos() const @@ -70,7 +94,13 @@ Cwise::cos() const /** \array_module * - * \returns an expression of the coefficient-wise sine of *this. */ + * \returns an expression of the coefficient-wise sine of *this. + * + * Example: \include Cwise_sin.cpp + * Output: \verbinclude Cwise_sin.out + * + * \sa cos(), exp() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_sin_op) Cwise::sin() const @@ -81,7 +111,13 @@ Cwise::sin() const /** \array_module * - * \returns an expression of the coefficient-wise power of *this to the given exponent. */ + * \returns an expression of the coefficient-wise power of *this to the given exponent. + * + * Example: \include Cwise_pow.cpp + * Output: \verbinclude Cwise_pow.out + * + * \sa exp(), log() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_pow_op) Cwise::pow(const Scalar& exponent) const @@ -92,7 +128,13 @@ Cwise::pow(const Scalar& exponent) const /** \array_module * - * \returns an expression of the coefficient-wise inverse of *this. */ + * \returns an expression of the coefficient-wise inverse of *this. + * + * Example: \include Cwise_inverse.cpp + * Output: \verbinclude Cwise_inverse.out + * + * \sa operator/(), operator*() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_inverse_op) Cwise::inverse() const @@ -102,7 +144,13 @@ Cwise::inverse() const /** \array_module * - * \returns an expression of the coefficient-wise square of *this. */ + * \returns an expression of the coefficient-wise square of *this. + * + * Example: \include Cwise_square.cpp + * Output: \verbinclude Cwise_square.out + * + * \sa operator/(), operator*(), abs2() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_square_op) Cwise::square() const @@ -112,7 +160,13 @@ Cwise::square() const /** \array_module * - * \returns an expression of the coefficient-wise cube of *this. */ + * \returns an expression of the coefficient-wise cube of *this. + * + * Example: \include Cwise_cube.cpp + * Output: \verbinclude Cwise_cube.out + * + * \sa square(), pow() + */ template inline const EIGEN_CWISE_UNOP_RETURN_TYPE(ei_scalar_cube_op) Cwise::cube() const @@ -127,9 +181,10 @@ Cwise::cube() const * * \returns an expression of the coefficient-wise \< operator of *this and \a other * - * See MatrixBase::all() for an example. + * Example: \include Cwise_less.cpp + * Output: \verbinclude Cwise_less.out * - * \sa class CwiseBinaryOp + * \sa MatrixBase::all(), MatrixBase::any(), operator>(), operator<=() */ template template @@ -143,7 +198,10 @@ Cwise::operator<(const MatrixBase &other) const * * \returns an expression of the coefficient-wise \<= operator of *this and \a other * - * \sa class CwiseBinaryOp + * Example: \include Cwise_less_equal.cpp + * Output: \verbinclude Cwise_less_equal.out + * + * \sa MatrixBase::all(), MatrixBase::any(), operator>=(), operator<() */ template template @@ -157,9 +215,10 @@ Cwise::operator<=(const MatrixBase &other) const * * \returns an expression of the coefficient-wise \> operator of *this and \a other * - * See MatrixBase::all() for an example. + * Example: \include Cwise_greater.cpp + * Output: \verbinclude Cwise_greater.out * - * \sa class CwiseBinaryOp + * \sa MatrixBase::all(), MatrixBase::any(), operator>=(), operator<() */ template template @@ -173,7 +232,10 @@ Cwise::operator>(const MatrixBase &other) const * * \returns an expression of the coefficient-wise \>= operator of *this and \a other * - * \sa class CwiseBinaryOp + * Example: \include Cwise_greater_equal.cpp + * Output: \verbinclude Cwise_greater_equal.out + * + * \sa MatrixBase::all(), MatrixBase::any(), operator>(), operator<=() */ template template @@ -187,7 +249,15 @@ Cwise::operator>=(const MatrixBase &other) const * * \returns an expression of the coefficient-wise == operator of *this and \a other * - * \sa class CwiseBinaryOp + * \warning this performs an exact comparison, which is generally a bad idea with floating-point types. + * In order to check for equality between two vectors or matrices with floating-point coefficients, it is + * generally a far better idea to use a fuzzy comparison as provided by MatrixBase::isApprox() and + * MatrixBase::isMuchSmallerThan(). + * + * Example: \include Cwise_equal_equal.cpp + * Output: \verbinclude Cwise_equal_equal.out + * + * \sa MatrixBase::all(), MatrixBase::any(), MatrixBase::isApprox(), MatrixBase::isMuchSmallerThan() */ template template @@ -201,7 +271,15 @@ Cwise::operator==(const MatrixBase &other) const * * \returns an expression of the coefficient-wise != operator of *this and \a other * - * \sa class CwiseBinaryOp + * \warning this performs an exact comparison, which is generally a bad idea with floating-point types. + * In order to check for equality between two vectors or matrices with floating-point coefficients, it is + * generally a far better idea to use a fuzzy comparison as provided by MatrixBase::isApprox() and + * MatrixBase::isMuchSmallerThan(). + * + * Example: \include Cwise_not_equal.cpp + * Output: \verbinclude Cwise_not_equal.out + * + * \sa MatrixBase::all(), MatrixBase::any(), MatrixBase::isApprox(), MatrixBase::isMuchSmallerThan() */ template template @@ -213,7 +291,14 @@ Cwise::operator!=(const MatrixBase &other) const /** \array_module - * \returns an expression of \c *this with each coeff incremented by the constant \a scalar */ + * + * \returns an expression of \c *this with each coeff incremented by the constant \a scalar + * + * Example: \include Cwise_plus.cpp + * Output: \verbinclude Cwise_plus.out + * + * \sa operator+=(), operator-() + */ template inline const typename Cwise::ScalarAddReturnType Cwise::operator+(const Scalar& scalar) const @@ -222,7 +307,14 @@ Cwise::operator+(const Scalar& scalar) const } /** \array_module - * \see operator+() */ + * + * Adds the given \a scalar to each coeff of this expression. + * + * Example: \include Cwise_plus_equal.cpp + * Output: \verbinclude Cwise_plus_equal.out + * + * \sa operator+(), operator-=() + */ template inline ExpressionType& Cwise::operator+=(const Scalar& scalar) { @@ -230,7 +322,14 @@ inline ExpressionType& Cwise::operator+=(const Scalar& scalar) } /** \array_module - * \returns an expression of \c *this with each coeff decremented by the constant \a scalar */ + * + * \returns an expression of \c *this with each coeff decremented by the constant \a scalar + * + * Example: \include Cwise_minus.cpp + * Output: \verbinclude Cwise_minus.out + * + * \sa operator+(), operator-=() + */ template inline const typename Cwise::ScalarAddReturnType Cwise::operator-(const Scalar& scalar) const @@ -239,7 +338,15 @@ Cwise::operator-(const Scalar& scalar) const } /** \array_module - * \see operator- */ + * + * Substracts the given \a scalar from each coeff of this expression. + * + * Example: \include Cwise_minus_equal.cpp + * Output: \verbinclude Cwise_minus_equal.out + * + * \sa operator+=(), operator-() + */ + template inline ExpressionType& Cwise::operator-=(const Scalar& scalar) { diff --git a/Eigen/src/Array/PartialRedux.h b/Eigen/src/Array/PartialRedux.h index 48daad770..bdd657368 100644 --- a/Eigen/src/Array/PartialRedux.h +++ b/Eigen/src/Array/PartialRedux.h @@ -139,10 +139,13 @@ struct ei_member_redux { * \param ExpressionType the type of the object on which to do partial reductions * \param Direction indicates the direction of the redux (Vertical or Horizontal) * - * This class represents an expression with additional partial reduction features. + * This class represents a pseudo expression with partial reduction features. * It is the return type of MatrixBase::colwise() and MatrixBase::rowwise() * and most of the time this is the only way it is used. * + * Example: \include MatrixBase_colwise.cpp + * Output: \verbinclude MatrixBase_colwise.out + * * \sa MatrixBase::colwise(), MatrixBase::rowwise(), class PartialReduxExpr */ template class PartialRedux @@ -180,30 +183,50 @@ template class PartialRedux /** \returns a row (or column) vector expression of the smallest coefficient * of each column (or row) of the referenced expression. + * + * Example: \include PartialRedux_minCoeff.cpp + * Output: \verbinclude PartialRedux_minCoeff.out + * * \sa MatrixBase::minCoeff() */ const typename ReturnType::Type minCoeff() const { return _expression(); } /** \returns a row (or column) vector expression of the largest coefficient * of each column (or row) of the referenced expression. + * + * Example: \include PartialRedux_maxCoeff.cpp + * Output: \verbinclude PartialRedux_maxCoeff.out + * * \sa MatrixBase::maxCoeff() */ const typename ReturnType::Type maxCoeff() const { return _expression(); } /** \returns a row (or column) vector expression of the squared norm * of each column (or row) of the referenced expression. + * + * Example: \include PartialRedux_norm2.cpp + * Output: \verbinclude PartialRedux_norm2.out + * * \sa MatrixBase::norm2() */ const typename ReturnType::Type norm2() const { return _expression(); } /** \returns a row (or column) vector expression of the norm * of each column (or row) of the referenced expression. + * + * Example: \include PartialRedux_norm.cpp + * Output: \verbinclude PartialRedux_norm.out + * * \sa MatrixBase::norm() */ const typename ReturnType::Type norm() const { return _expression(); } /** \returns a row (or column) vector expression of the sum * of each column (or row) of the referenced expression. + * + * Example: \include PartialRedux_sum.cpp + * Output: \verbinclude PartialRedux_sum.out + * * \sa MatrixBase::sum() */ const typename ReturnType::Type sum() const { return _expression(); } @@ -216,7 +239,10 @@ template class PartialRedux * * \returns a PartialRedux wrapper of *this providing additional partial reduction operations * - * \sa class PartialRedux + * Example: \include MatrixBase_colwise.cpp + * Output: \verbinclude MatrixBase_colwise.out + * + * \sa rowwise(), class PartialRedux */ template inline const PartialRedux @@ -229,7 +255,10 @@ MatrixBase::colwise() const * * \returns a PartialRedux wrapper of *this providing additional partial reduction operations * - * \sa class PartialRedux + * Example: \include MatrixBase_rowwise.cpp + * Output: \verbinclude MatrixBase_rowwise.out + * + * \sa colwise(), class PartialRedux */ template inline const PartialRedux -- cgit v1.2.3