Improve documentation to function copy_from() of class BlockMatrixBase, chunkSparseMa...

diff --git a/include/deal.II/lac/block_matrix_base.h b/include/deal.II/lac/block_matrix_base.h
index 599673b319b8b9930105a5e29227696c24a2bf81..080cb654b2ca75d3704af2f67fbad934fdbc93a5 100644 (file)
--- a/include/deal.II/lac/block_matrix_base.h
+++ b/include/deal.II/lac/block_matrix_base.h
@@ -377,12 +377,15 @@ public:
   ~BlockMatrixBase ();
 
   /**
-   * Copy the given matrix to this one.  The operation throws an error if the
-   * sparsity patterns of the two involved matrices do not point to the same
-   * object, since in this case the copy operation is cheaper. Since this
-   * operation is nonetheless not for free, we do not make it available through
-   * operator=(), since this may lead to unwanted usage, e.g. in copy
-   * arguments to functions, which should really be arguments by reference.
+   * Copy the matrix given as argument into the current object.
+   *
+   * Copying matrices is an expensive operation that we do not want to happen
+   * by accident through compiler generated code for <code>operator=</code>.
+   * (This would happen, for example, if one accidentally declared a function
+   * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
+   * The functionality of copying matrices is implemented in this member function
+   * instead. All copy operations of objects of this type therefore require an
+   * explicit function call.
    *
    * The source matrix may be a matrix of arbitrary type, as long as its data
    * type is convertible to the data type of this matrix.

diff --git a/include/deal.II/lac/chunk_sparse_matrix.h b/include/deal.II/lac/chunk_sparse_matrix.h
index 71875f2d6c46275095c16bc9266e46f1ceddfa0d..9cf4a003951c1d2bdc72ff224b83030894211fbd 100644 (file)
--- a/include/deal.II/lac/chunk_sparse_matrix.h
+++ b/include/deal.II/lac/chunk_sparse_matrix.h
@@ -692,12 +692,15 @@ public:
   void symmetrize ();
 
   /**
-   * Copy the given matrix to this one.  The operation throws an error if the
-   * sparsity patterns of the two involved matrices do not point to the same
-   * object, since in this case the copy operation is cheaper. Since this
-   * operation is nonetheless not for free, we do not make it available through
-   * <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
-   * arguments to functions, which should really be arguments by reference.
+   * Copy the matrix given as argument into the current object.
+   *
+   * Copying matrices is an expensive operation that we do not want to happen
+   * by accident through compiler generated code for <code>operator=</code>.
+   * (This would happen, for example, if one accidentally declared a function
+   * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
+   * The functionality of copying matrices is implemented in this member function
+   * instead. All copy operations of objects of this type therefore require an
+   * explicit function call.
    *
    * The source matrix may be a matrix of arbitrary type, as long as its data
    * type is convertible to the data type of this matrix.

diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h
index 96138f2508a1b82b07addcb51631824f37bfa602..86988585a4989e9a8ac4b520682d6e111d1a973b 100644 (file)
--- a/include/deal.II/lac/sparse_matrix.h
+++ b/include/deal.II/lac/sparse_matrix.h
@@ -869,13 +869,15 @@ public:
   void symmetrize ();
 
   /**
-   * Copy the given matrix to this one.  The operation triggers an assertion
-   * if the sparsity patterns of the two involved matrices do not point to the
-   * same object, since in this case the copy operation is cheaper. Since this
-   * operation is nonetheless not for free, we do not make it available
-   * through <tt>operator =</tt>, since this may lead to unwanted usage,
-   * e.g. in copy arguments to functions, which should really be arguments by
-   * reference.
+   * Copy the matrix given as argument into the current object.
+   *
+   * Copying matrices is an expensive operation that we do not want to happen
+   * by accident through compiler generated code for <code>operator=</code>.
+   * (This would happen, for example, if one accidentally declared a function
+   * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
+   * The functionality of copying matrices is implemented in this member function
+   * instead. All copy operations of objects of this type therefore require an
+   * explicit function call.
    *
    * The source matrix may be a matrix of arbitrary type, as long as its data
    * type is convertible to the data type of this matrix.

diff --git a/include/deal.II/lac/sparse_matrix_ez.h b/include/deal.II/lac/sparse_matrix_ez.h
index 14e3bdcf05651ecb18a2457c1385a985d33d11ae..409c296a0fd2b4360878123f4b4e7ebadc5535b0 100644 (file)
--- a/include/deal.II/lac/sparse_matrix_ez.h
+++ b/include/deal.II/lac/sparse_matrix_ez.h
@@ -508,12 +508,15 @@ public:
             const bool       col_indices_are_sorted = false);
 
   /**
-   * Copy the given matrix to this one.  The operation throws an error if the
-   * sparsity patterns of the two involved matrices do not point to the same
-   * object, since in this case the copy operation is cheaper. Since this
-   * operation is nonetheless not for free, we do not make it available through
-   * <tt>operator =</tt>, since this may lead to unwanted usage, e.g. in copy
-   * arguments to functions, which should really be arguments by reference.
+   * Copy the matrix given as argument into the current object.
+   *
+   * Copying matrices is an expensive operation that we do not want to happen
+   * by accident through compiler generated code for <code>operator=</code>.
+   * (This would happen, for example, if one accidentally declared a function
+   * argument of the current type <i>by value</i> rather than <i>by reference</i>.)
+   * The functionality of copying matrices is implemented in this member function
+   * instead. All copy operations of objects of this type therefore require an
+   * explicit function call.
    *
    * The source matrix may be a matrix of arbitrary type, as long as its data
    * type is convertible to the data type of this matrix.