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 11aced3b74046d6ccc3d49c2c810f9b467531b19..33d3ef92a661b24fdf342732df5ca9bf4200e142 100644 (file)
--- 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 b441defa8d4c33c899a0628b2b7f0dc5ace292c7..ed85850912df0749a73e150fb35553d79c36af14 100644 (file)
--- 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 895c02e08175386e1e23944ad46553a1dfa61f54..38840dd53a5672fb4cd21e73dbc00d38c6927d40 100644 (file)
--- 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 &);