From: Stefano Zampini <stefano.zampini@gmail.com>
Date: Mon, 16 Jan 2023 14:19:01 +0000 (+0300)
Subject: Improve documentation
X-Git-Tag: v9.5.0-rc1~600^2~1
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9fc69d191e7ca161f4b8c0a72cb36192c32934a2;p=dealii.git

Improve documentation
---

diff --git a/include/deal.II/lac/petsc_block_sparse_matrix.h b/include/deal.II/lac/petsc_block_sparse_matrix.h
index 11aced3b74..33d3ef92a6 100644
--- a/include/deal.II/lac/petsc_block_sparse_matrix.h
+++ b/include/deal.II/lac/petsc_block_sparse_matrix.h
@@ -103,7 +103,11 @@ namespace PETScWrappers
       BlockSparseMatrix() = default;
 
       /**
-       * Create a BlockSparseMatrix with a PETSc Mat
+       * Create a BlockSparseMatrix with a PETSc Mat that describes the entire
+       * block matrix.
+       * It infers the number of blocks from the Mat if it is of type MATNEST,
+       * otherwise the block operator will only have a single block.
+       * Internally, we always store a MATNEST matrix.
        */
       explicit BlockSparseMatrix(const Mat &);
 
@@ -300,8 +304,8 @@ namespace PETScWrappers
        * are doing.
        *
        * The PETSc Mat object returned here describes the *entire* matrix,
-       * not just one of its blocks. Internally, this is done by creating
-       * a "nested" matrix using Petsc's MatCreateNest object whose individual
+       * not just one of its blocks. Internally, this is done using
+       * a "nested" matrix using PETSc's MATNEST object whose individual
        * blocks are the blocks of this matrix.
        */
       Mat &
@@ -311,7 +315,7 @@ namespace PETScWrappers
       /**
        * A PETSc Mat object that describes the entire block matrix.
        * Internally, this is done by creating
-       * a "nested" matrix using Petsc's MatCreateNest object whose individual
+       * a "nested" matrix using PETSc's MATNEST object whose individual
        * blocks are the blocks of this matrix.
        */
       Mat petsc_nest_matrix = nullptr;
diff --git a/include/deal.II/lac/petsc_block_vector.h b/include/deal.II/lac/petsc_block_vector.h
index b441defa8d..ed85850912 100644
--- a/include/deal.II/lac/petsc_block_vector.h
+++ b/include/deal.II/lac/petsc_block_vector.h
@@ -132,10 +132,12 @@ namespace PETScWrappers
 
       /**
        * Create a BlockVector with a PETSc Vec
+       * It infers the number of blocks from the Vec if it is of type VECNEST,
+       * otherwise the block vector will only have a single block.
+       * Internally, we always store a VECNEST vector.
        */
       explicit BlockVector(Vec v);
 
-
       /**
        * Destructor. Clears memory
        */
diff --git a/include/deal.II/lac/petsc_sparse_matrix.h b/include/deal.II/lac/petsc_sparse_matrix.h
index 895c02e081..38840dd53a 100644
--- a/include/deal.II/lac/petsc_sparse_matrix.h
+++ b/include/deal.II/lac/petsc_sparse_matrix.h
@@ -77,7 +77,9 @@ namespace PETScWrappers
 
     /**
      * Initialize a Matrix from a PETSc Mat object. Note that we do not copy
-     * the matrix.
+     * the matrix. The Mat object is referenced by the newly created instance
+     * of the class using PetscObjectReference. This is in line with the PETSc
+     * approach to object ownership, which mimicks std::shared_ptr.
      */
     explicit SparseMatrix(const Mat &);
 
@@ -396,7 +398,9 @@ namespace PETScWrappers
 
       /**
        * Initialize a SparseMatrix from a PETSc Mat object. Note that we do not
-       * copy the matrix.
+       * copy the matrix. The Mat object is referenced by the newly created
+       * instance of the class using PetscObjectReference. This is in line with
+       * the PETSc approach to object ownership, which mimicks std::shared_ptr.
        */
       explicit SparseMatrix(const Mat &);