From: David Wells <drwells@email.unc.edu>
Date: Sun, 5 Nov 2023 14:43:06 +0000 (-0500)
Subject: Clarify when RemotePointEvaluation is reinitialized.
X-Git-Tag: relicensing~311^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16244%2Fhead;p=dealii.git

Clarify when RemotePointEvaluation is reinitialized.
---

diff --git a/include/deal.II/numerics/vector_tools_evaluate.h b/include/deal.II/numerics/vector_tools_evaluate.h
index 69ecd574d9..c33c060dd1 100644
--- a/include/deal.II/numerics/vector_tools_evaluate.h
+++ b/include/deal.II/numerics/vector_tools_evaluate.h
@@ -68,8 +68,9 @@ namespace VectorTools
   } // namespace EvaluationFlags
 
   /**
-   * Given a (distributed) solution vector @p vector, evaluate the values at
-   * the (arbitrary and even remote) points specified by @p evaluation_points.
+   * Given a (distributed) solution vector @p vector, reinitialize @p cache and
+   * evaluate the values at the (arbitrary and even remote) points specified by
+   * @p evaluation_points.
    *
    * The following code snippet shows the usage of this function. Given
    * a Mapping object, a DoFHandler object, and solution vector as well as a
@@ -80,13 +81,15 @@ namespace VectorTools
    * further function calls (see also the function below).
    *
    * @code
-   * // first usage: set up cache
    * Utilities::MPI::RemotePointEvaluation<dim, spacedim> cache;
    *
+   * // Set up the cache and perform evaluation. This overload always
+   * // reinitializes the RemotePointEvaluation cache object so, typically, it
+   * // should only be called once.
    * const auto result_1 = VectorTools::point_values(
    *   mapping, dof_handler_1, vector_1, evaluation_points, cache);
    *
-   * // further usages: reuse the cache
+   * // This overload does not initialize or reinitialize the cache.
    * const auto result_2 = VectorTools::point_values(
    *   cache, dof_handler_2, vector_2);
    * @endcode