Add doxygen documentation to SerialDenseVector

Author: bgoderbauer

src/core/linalg/src/dense/4C_linalg_serialdensevector.cpp

@@ -40,6 +40,7 @@ namespace Core::LinAlg
   int SerialDenseVector::numRows() const { return vec_.numRows(); }
   double SerialDenseVector::normInf() const { return vec_.normInf(); }
   double SerialDenseVector::normOne() const { return vec_.normOne(); }
+  double SerialDenseVector::norm2() const { return vec_.normFrobenius(); }
   double SerialDenseVector::normFrobenius() const { return vec_.normFrobenius(); }
   bool SerialDenseVector::empty() const { return vec_.length() == 0; }
 
@@ -94,7 +95,7 @@ namespace Core::LinAlg
 /*----------------------------------------------------------------------*
  |  Compute vector 2-norm                                               |
  *----------------------------------------------------------------------*/
-double Core::LinAlg::norm2(const Core::LinAlg::SerialDenseVector& v) { return v.normFrobenius(); }
+double Core::LinAlg::norm2(const Core::LinAlg::SerialDenseVector& v) { return v.norm2(); }
 
 /*----------------------------------------------------------------------*
  |  b = alpha*a + beta*b                                                |

src/core/linalg/src/dense/4C_linalg_serialdensevector.hpp

@@ -23,7 +23,9 @@ FOUR_C_NAMESPACE_OPEN
 namespace Core::LinAlg
 {
   /*!
-   * \brief A wrapper around Teuchos::SerialDenseVector
+   * \brief Composition wrapper for Teuchos::SerialDenseVector.
+   *
+   * Access to the underlying Trilinos object is explicit via base().
    */
   class SerialDenseVector
   {
@@ -32,46 +34,72 @@ namespace Core::LinAlg
     using scalarType = double;
     using Base = Teuchos::SerialDenseVector<ordinalType, scalarType>;
 
-    // --- constructors ---
+    /** \name Construction */
+    //@{
     SerialDenseVector() = default;
     SerialDenseVector(int length);
     SerialDenseVector(int length, bool zeroOut);
+
+    /*! \brief Construct from user-provided storage.
+     *
+     * Behavior (view/copy) follows \p cv semantics of Teuchos::DataAccess.
+     */
     SerialDenseVector(Teuchos::DataAccess cv, double* values, int length);
+
+    /*! \brief Construct from underlying Trilinos vector.
+     *
+     * \note \p trans is accepted for API compatibility and validated.
+     */
     SerialDenseVector(const Base& source, Teuchos::ETransp trans = Teuchos::NO_TRANS);
+    //@}
 
     // NOLINTBEGIN(readability-identifier-naming)
 
-    // --- size queries ---
+    /** \name Size queries and norms */
+    //@{
     [[nodiscard]] int length() const;
     [[nodiscard]] int num_rows() const;
     [[nodiscard]] int numRows() const;
     [[nodiscard]] double normInf() const;
     [[nodiscard]] double normOne() const;
+    [[nodiscard]] double norm2() const;
     [[nodiscard]] double normFrobenius() const;
     [[nodiscard]] bool empty() const;
+    //@}
 
-    // --- element access ---
+    /** \name Element access */
+    //@{
     double& operator()(int i) { return vec_(i); }
     const double& operator()(int i) const { return vec_(i); }
     double& operator[](int i) { return vec_[i]; }
     const double& operator[](int i) const { return vec_[i]; }
+    //@}
 
-    // --- data access ---
-    //! Returns a pointer to the raw data.
+    /** \name Raw data access */
+    //@{
+    /*! \brief Returns pointer to contiguous vector storage.
+     *
+     * The const overload follows Teuchos semantics and returns mutable data.
+     */
     double* values() const;
-    //! Returns a pointer to the raw data.
+
+    //! Alias for values().
     double* data() const;
+    //@}
 
-    // --- modifiers ---
+    /** \name Modifiers */
+    //@{
     int size(int length);
     int Size(int length);
     int resize(int length);
     int scale(double alpha);
     int put_scalar(double val = 0.0);
     int putScalar(double val = 0.0);
     void assign(const SerialDenseVector& source);
+    //@}
 
-    // --- algebraic operations ---
+    /** \name Algebraic operations */
+    //@{
     SerialDenseVector& operator+=(const SerialDenseVector& other);
     double dot(const SerialDenseVector& other) const;
     int multiply(Teuchos::ETransp transa, Teuchos::ETransp transb, double alpha,
@@ -81,39 +109,52 @@ namespace Core::LinAlg
         const Teuchos::SerialDenseMatrix<ordinalType, scalarType>& A, const SerialDenseVector& B,
         double beta);
     void print(std::ostream& out) const;
+    //@}
 
     // NOLINTEND(readability-identifier-naming)
 
-    // --- access to underlying Trilinos object ---
+    /** \name Trilinos interoperability */
+    //@{
+    /*! \brief Access the wrapped Trilinos vector for low-level interfaces. */
     Base& base();
+
+    /*! \brief Const access variant of base(). */
     const Base& base() const;
+    //@}
 
-    /**
-     * Get the vector as a std::span.
-     */
+    /** \name Span views */
+    //@{
+    //! Returns a read-only span view over the current vector data.
     [[nodiscard]] std::span<const double> as_span() const { return std::span(values(), length()); }
 
-    /**
-     * Get the vector as a std::span.
-     */
+    //! Returns a mutable span view over the current vector data.
     [[nodiscard]] std::span<double> as_span() { return std::span(values(), length()); }
+    //@}
 
    private:
+    /*! \cond INTERNAL */
     Base vec_;
+    /*! \endcond */
   };
 
   // type definition for serial integer vector
   using IntSerialDenseVector = Teuchos::SerialDenseVector<int, int>;
 
+  /** \name Free vector utilities */
+  //@{
+
   /*!
-    \brief Update vector components with scaled values of a,
-           b = alpha*a + beta*b
+    \brief Update vector components with scaled values.
+
+    Computes \p b = \p alpha * \p a + \p beta * \p b.
     */
   void update(double alpha, const SerialDenseVector& a, double beta, SerialDenseVector& b);
 
-  // wrapper function to compute Norm of vector
+  //! Euclidean vector norm.
   double norm2(const SerialDenseVector& v);
 
+  //@}
+
   // output stream operator
   inline std::ostream& operator<<(std::ostream& out, const SerialDenseVector& vec)
   {

src/core/linalg/src/sparse/4C_linalg_sparsematrix.hpp

@@ -199,8 +199,12 @@ namespace Core::LinAlg
         const Core::LinAlg::SerialDenseMatrix& Aele, const std::vector<int>& lmrow,
         const std::vector<int>& lmrowowner, const std::vector<int>& lmcol) override;
 
-    /// assemble method for a local vector (interpreted as column matrix)
-    /// lmcol must match the column count of the generated view (typically 1).
+    /*!
+      \brief Assemble a local vector by interpreting it as a column matrix.
+
+      \note The size of \p lmcol must match the generated view column count
+      (typically 1).
+    */
     void assemble(int eid, const std::vector<int>& lmstride,
         const Core::LinAlg::SerialDenseVector& Vele, const std::vector<int>& lmrow,
         const std::vector<int>& lmrowowner, const std::vector<int>& lmcol)
@@ -215,8 +219,12 @@ namespace Core::LinAlg
         const std::vector<int>& lmrow, const std::vector<int>& lmrowowner,
         const std::vector<int>& lmcol);
 
-    /// assemble method for a local vector (interpreted as column matrix)
-    /// lmcol must match the column count of the generated view (typically 1).
+    /*!
+      \brief Assemble a local vector by interpreting it as a column matrix.
+
+      \note The size of \p lmcol must match the generated view column count
+      (typically 1).
+    */
     void assemble(int eid, const Core::LinAlg::SerialDenseVector& Vele,
         const std::vector<int>& lmrow, const std::vector<int>& lmrowowner,
         const std::vector<int>& lmcol)

src/core/linalg/src/sparse/4C_linalg_sparseoperator.hpp

@@ -163,8 +163,12 @@ namespace Core::LinAlg
         const Core::LinAlg::SerialDenseMatrix& Aele, const std::vector<int>& lmrow,
         const std::vector<int>& lmrowowner, const std::vector<int>& lmcol) = 0;
 
-    /// assemble method for a local vector (interpreted as column matrix)
-    /// lmcol must match the column count of the generated view (typically 1).
+    /*!
+      \brief Assemble a local vector by interpreting it as a column matrix.
+
+      \note The size of \p lmcol must match the generated view column count
+      (typically 1).
+    */
     void assemble(int eid, const std::vector<int>& lmstride,
         const Core::LinAlg::SerialDenseVector& Vele, const std::vector<int>& lmrow,
         const std::vector<int>& lmrowowner, const std::vector<int>& lmcol)