From ba4d7304e2e165a71187a5ff7b6799733e0025d4 Mon Sep 17 00:00:00 2001
From: Arthur <afeeney@umass.edu>
Date: Wed, 8 Jun 2022 17:46:32 +0000
Subject: [PATCH] Document DiagonalBase

---
 Eigen/src/Core/DiagonalMatrix.h | 126 +++++++++++++++++++-------------
 1 file changed, 75 insertions(+), 51 deletions(-)

diff --git a/Eigen/src/Core/DiagonalMatrix.h b/Eigen/src/Core/DiagonalMatrix.h
index ad33f7f63..405cc712f 100644
--- a/Eigen/src/Core/DiagonalMatrix.h
+++ b/Eigen/src/Core/DiagonalMatrix.h
@@ -13,9 +13,21 @@
 
 #include "./InternalHeaderCheck.h"
 
-namespace Eigen { 
+namespace Eigen {
 
-#ifndef EIGEN_PARSED_BY_DOXYGEN
+/** \class DiagonalBase
+ * \ingroup Core_Module
+ *
+ * \brief Base class for diagonal matrices and expressions
+ *
+ * This is the base class that is inherited by diagonal matrix and related expression
+ * types, which internally use a vector for storing the diagonal entries. Diagonal
+ * types always represent square matrices.
+ *
+ * \tparam Derived is the derived type, a DiagonalMatrix or DiagonalWrapper.
+ *
+ * \sa class DiagonalMatrix, class DiagonalWrapper
+ */
 template<typename Derived>
 class DiagonalBase : public EigenBase<Derived>
 {
@@ -39,24 +51,35 @@ class DiagonalBase : public EigenBase<Derived>
     typedef DenseMatrixType DenseType;
     typedef DiagonalMatrix<Scalar,DiagonalVectorType::SizeAtCompileTime,DiagonalVectorType::MaxSizeAtCompileTime> PlainObject;
 
+    /** \returns a reference to the derived object. */
     EIGEN_DEVICE_FUNC
     inline const Derived& derived() const { return *static_cast<const Derived*>(this); }
+    /** \returns a const reference to the derived object. */
     EIGEN_DEVICE_FUNC
     inline Derived& derived() { return *static_cast<Derived*>(this); }
 
+    /**
+     * Constructs a dense matrix from \c *this. Note, this directly returns a dense matrix type,
+     * not an expression.
+     * \returns A dense matrix, with its diagonal entries set from the the derived object. */
     EIGEN_DEVICE_FUNC
     DenseMatrixType toDenseMatrix() const { return derived(); }
 
+    /** \returns a reference to the derived object's vector of diagonal coefficients. */
     EIGEN_DEVICE_FUNC
     inline const DiagonalVectorType& diagonal() const { return derived().diagonal(); }
+    /** \returns a const reference to the derived object's vector of diagonal coefficients. */
     EIGEN_DEVICE_FUNC
     inline DiagonalVectorType& diagonal() { return derived().diagonal(); }
 
+    /** \returns the number of rows. */
     EIGEN_DEVICE_FUNC EIGEN_CONSTEXPR 
     inline Index rows() const { return diagonal().size(); }
+    /** \returns the number of columns. */
     EIGEN_DEVICE_FUNC EIGEN_CONSTEXPR 
     inline Index cols() const { return diagonal().size(); }
 
+    /** \returns the diagonal matrix product of \c *this by the dense matrix, \a matrix */
     template<typename MatrixDerived>
     EIGEN_DEVICE_FUNC
     const Product<Derived,MatrixDerived,LazyProduct>
@@ -69,72 +92,73 @@ class DiagonalBase : public EigenBase<Derived>
     using DiagonalProductReturnType = DiagonalWrapper<const EIGEN_CWISE_BINARY_RETURN_TYPE(
         DiagonalVectorType, typename OtherDerived::DiagonalVectorType, product)>;
 
+    /** \returns the diagonal matrix product of \c *this by the diagonal matrix \a other */
     template <typename OtherDerived>
     EIGEN_DEVICE_FUNC const DiagonalProductReturnType<OtherDerived> operator*(
         const DiagonalBase<OtherDerived>& other) const {
-      return (diagonal().cwiseProduct(other.diagonal())).asDiagonal();
+      return diagonal().cwiseProduct(other.diagonal()).asDiagonal();
     }
 
-    typedef DiagonalWrapper<const CwiseUnaryOp<internal::scalar_inverse_op<Scalar>, const DiagonalVectorType> > InverseReturnType;
+    using DiagonalInverseReturnType =
+        DiagonalWrapper<const CwiseUnaryOp<internal::scalar_inverse_op<Scalar>, const DiagonalVectorType>>;
+
+    /** \returns the inverse \c *this. Computed as the coefficient-wise inverse of the diagonal. */
     EIGEN_DEVICE_FUNC
-    inline const InverseReturnType
-    inverse() const
-    {
-      return InverseReturnType(diagonal().cwiseInverse());
-    }
-    
+    inline const DiagonalInverseReturnType inverse() const { return diagonal().cwiseInverse().asDiagonal(); }
+
+    using DiagonalScaleReturnType =
+        DiagonalWrapper<const EIGEN_EXPR_BINARYOP_SCALAR_RETURN_TYPE(DiagonalVectorType, Scalar, product)>;
+
+    /** \returns the product of \c *this by the scalar \a scalar */
     EIGEN_DEVICE_FUNC
-    inline const DiagonalWrapper<const EIGEN_EXPR_BINARYOP_SCALAR_RETURN_TYPE(DiagonalVectorType,Scalar,product) >
-    operator*(const Scalar& scalar) const
-    {
-      return DiagonalWrapper<const EIGEN_EXPR_BINARYOP_SCALAR_RETURN_TYPE(DiagonalVectorType,Scalar,product) >(diagonal() * scalar);
-    }
-    EIGEN_DEVICE_FUNC
-    friend inline const DiagonalWrapper<const EIGEN_SCALAR_BINARYOP_EXPR_RETURN_TYPE(Scalar,DiagonalVectorType,product) >
-    operator*(const Scalar& scalar, const DiagonalBase& other)
-    {
-      return DiagonalWrapper<const EIGEN_SCALAR_BINARYOP_EXPR_RETURN_TYPE(Scalar,DiagonalVectorType,product) >(scalar * other.diagonal());
+    inline const DiagonalScaleReturnType operator*(const Scalar& scalar) const {
+      return (diagonal() * scalar).asDiagonal();
     }
 
-    template<typename OtherDerived>
+    using ScaleDiagonalReturnType =
+        DiagonalWrapper<const EIGEN_SCALAR_BINARYOP_EXPR_RETURN_TYPE(Scalar, DiagonalVectorType, product)>;
+
+    /** \returns the product of a scalar and the diagonal matrix \a other */
     EIGEN_DEVICE_FUNC
-    #ifdef EIGEN_PARSED_BY_DOXYGEN
-    inline unspecified_expression_type
-    #else
-    inline const DiagonalWrapper<const EIGEN_CWISE_BINARY_RETURN_TYPE(DiagonalVectorType,typename OtherDerived::DiagonalVectorType,sum) >
-    #endif
-    operator+(const DiagonalBase<OtherDerived>& other) const
-    {
+    friend inline const ScaleDiagonalReturnType operator*(const Scalar& scalar, const DiagonalBase& other) {
+      return (scalar * other.diagonal()).asDiagonal();
+    }
+
+    template <typename OtherDerived>
+    using DiagonalSumReturnType = DiagonalWrapper<const EIGEN_CWISE_BINARY_RETURN_TYPE(
+        DiagonalVectorType, typename OtherDerived::DiagonalVectorType, sum)>;
+
+    /** \returns the sum of \c *this and the diagonal matrix \a other */
+    template <typename OtherDerived>
+    EIGEN_DEVICE_FUNC inline const DiagonalSumReturnType<OtherDerived> operator+(
+        const DiagonalBase<OtherDerived>& other) const {
       return (diagonal() + other.diagonal()).asDiagonal();
     }
 
-    template<typename OtherDerived>
-    EIGEN_DEVICE_FUNC
-    #ifdef EIGEN_PARSED_BY_DOXYGEN
-    inline unspecified_expression_type
-    #else
-    inline const DiagonalWrapper<const EIGEN_CWISE_BINARY_RETURN_TYPE(DiagonalVectorType,typename OtherDerived::DiagonalVectorType,difference) >
-    #endif
-    operator-(const DiagonalBase<OtherDerived>& other) const
-    {
+    template <typename OtherDerived>
+    using DiagonalDifferenceReturnType = DiagonalWrapper<const EIGEN_CWISE_BINARY_RETURN_TYPE(
+        DiagonalVectorType, typename OtherDerived::DiagonalVectorType, difference)>;
+
+    /** \returns the difference of \c *this and the diagonal matrix \a other */
+    template <typename OtherDerived>
+    EIGEN_DEVICE_FUNC inline const DiagonalDifferenceReturnType<OtherDerived> operator-(
+        const DiagonalBase<OtherDerived>& other) const {
       return (diagonal() - other.diagonal()).asDiagonal();
     }
 };
 
-#endif
-
 /** \class DiagonalMatrix
-  * \ingroup Core_Module
-  *
-  * \brief Represents a diagonal matrix with its storage
-  *
-  * \tparam Scalar_ the type of coefficients
-  * \tparam SizeAtCompileTime the dimension of the matrix, or Dynamic
-  * \tparam MaxSizeAtCompileTime the dimension of the matrix, or Dynamic. This parameter is optional and defaults
-  *        to SizeAtCompileTime. Most of the time, you do not need to specify it.
-  *
-  * \sa class DiagonalWrapper
-  */
+ * \ingroup Core_Module
+ *
+ * \brief Represents a diagonal matrix with its storage
+ *
+ * \tparam Scalar_ the type of coefficients
+ * \tparam SizeAtCompileTime the dimension of the matrix, or Dynamic
+ * \tparam MaxSizeAtCompileTime the dimension of the matrix, or Dynamic. This parameter is optional and defaults
+ *        to SizeAtCompileTime. Most of the time, you do not need to specify it.
+ *
+ * \sa class DiagonalBase, class DiagonalWrapper
+ */
 
 namespace internal {
 template<typename Scalar_, int SizeAtCompileTime, int MaxSizeAtCompileTime>
@@ -414,6 +438,6 @@ struct Assignment<DstXprType, SrcXprType, Functor, Diagonal2Dense>
 
 } // namespace internal
 
-} // end namespace Eigen
+}  // end namespace Eigen
 
 #endif // EIGEN_DIAGONALMATRIX_H