From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Mon, 9 Dec 2019 17:51:58 +0000 (-0700)
Subject: Better document WorkStream and mesh_loop().
X-Git-Tag: v9.2.0-rc1~801^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=adab6bc862d92552570c8317697b74cef370d539;p=dealii.git

Better document WorkStream and mesh_loop().
---

diff --git a/include/deal.II/base/work_stream.h b/include/deal.II/base/work_stream.h
index 2538962781..228b2b4f0a 100644
--- a/include/deal.II/base/work_stream.h
+++ b/include/deal.II/base/work_stream.h
@@ -126,7 +126,11 @@ DEAL_II_NAMESPACE_OPEN
  * Once an item is processed by the copier, it is deleted and the ScratchData
  * and CopyData objects that were used in its computation are considered
  * unused and may be re-used for the next invocation of the worker function,
- * on this or another thread.
+ * on this or another thread. However, the WorkStream functions make no
+ * attempt to reset these objects to any kind of pristine state -- a worker
+ * should assume that the CopyData object it gets handed has prior content
+ * and clear it first in whatever manner seems appropriate, before putting
+ * content into it that can later be processed again by the copier.
  *
  * The member variables in ScratchData and CopyData can be accessed
  * independently of other concurrent uses of copies of these data structures.
@@ -139,7 +143,13 @@ DEAL_II_NAMESPACE_OPEN
  * CopyData can be resized in accordance with the number of local DoFs on the
  * current cell.
  *
- * The functions in this namespace only really work in parallel when
+ * @note For integration over cells and faces, it is often useful to use
+ * methods more specific to the task than the current function (which doesn't
+ * care whether the iterators are over cells, vector elements, or any other
+ * kind of range). An implementation of an interface specifically suited to
+ * integration is the MeshWorker::mesh_loop() function.
+ *
+ * @note The functions in this namespace only really work in parallel when
  * multithread mode was selected during deal.II configuration. Otherwise they
  * simply work on each item sequentially.
  *
diff --git a/include/deal.II/meshworker/mesh_loop.h b/include/deal.II/meshworker/mesh_loop.h
index 8c8d79f7cc..d301f6f665 100644
--- a/include/deal.II/meshworker/mesh_loop.h
+++ b/include/deal.II/meshworker/mesh_loop.h
@@ -120,7 +120,7 @@ namespace MeshWorker
    * identify the corresponding subface on either the current or the neighbor
    * faces.
    *
-   * This method externalises that logic (which is independent from user codes)
+   * This method externalizes that logic (which is independent from user codes)
    * and separates the assembly of face terms (internal faces, boundary faces,
    * or faces between different subdomain ids on parallel computations) from
    * the assembling on cells, allowing the user to specify two additional
@@ -128,7 +128,7 @@ namespace MeshWorker
    * are called automatically in each @p cell, according to the specific
    * AssembleFlags @p flags that are passed. The @p cell_worker is passed the
    * cell identifier, a ScratchData object, and a CopyData object, following
-   * the same principles of WorkStream::run. Internally the function passes to
+   * the same principles of WorkStream::run(). Internally the function passes to
    * @p boundary_worker, in addition to the above, also a @p face_no parameter
    * that identifies the face on which the integration should be performed. The
    * @p face_worker instead needs to identify the current face unambiguously
@@ -155,7 +155,14 @@ namespace MeshWorker
    *
    * The two data types ScratchData and CopyData need to have a working copy
    * constructor. ScratchData is only used in the worker function, while
-   * CopyData is the object passed from the worker to the copier.
+   * CopyData is the object passed from the worker to the copier. The CopyData
+   * object is reset to the value provided to this function every time this
+   * function visits a new cell (where it then calls the cell and face
+   * workers). In other words, no state carries over between calling the
+   * `copier` on one cell and the `cell_worker`/`face_worker`/`boundary_worker`
+   * functions on the next cell, and user code needs not reset the copy
+   * object either at the beginning of the cell integration or end of the
+   * copy operation.
    *
    * The queue_length argument indicates the number of items that can be live at
    * any given time. Each item consists of chunk_size elements of the input
@@ -164,7 +171,7 @@ namespace MeshWorker
    *
    * If your data objects are large, or their constructors are expensive, it is
    * helpful to keep in mind that queue_length copies of the ScratchData object
-   * and queue_length*chunk_size copies of the CopyData object are generated.
+   * and `queue_length*chunk_size` copies of the CopyData object are generated.
    *
    * @note More information about requirements on template types and meaning
    * of @p queue_length and @p chunk_size can be found in the documentation of the