From 31c9db954965938190688f751114f0da3a7146b9 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Mon, 11 Nov 2013 01:03:17 +0000
Subject: [PATCH] Provide documentation.

git-svn-id: https://svn.dealii.org/trunk@31615 0785d39b-7218-0410-832d-ea1e28bc413d
---
 deal.II/include/deal.II/base/graph_coloring.h |  8 ++--
 deal.II/include/deal.II/base/work_stream.h    | 46 +++++++++++++++++--
 2 files changed, 46 insertions(+), 8 deletions(-)

diff --git a/deal.II/include/deal.II/base/graph_coloring.h b/deal.II/include/deal.II/base/graph_coloring.h
index d83fc85139..963716dca3 100644
--- a/deal.II/include/deal.II/base/graph_coloring.h
+++ b/deal.II/include/deal.II/base/graph_coloring.h
@@ -443,9 +443,11 @@ namespace GraphColoring
    * cells adjacent to the faces of the current cell (in the case of
    * discontinuous Galerkin methods, because there one computes face integrals
    * coupling the degrees of freedom connected by a common face -- see step-12).
-   * More generally, however, the conflict set needs to contain all degrees of
-   * freedom for which anything is written into the matrix or right hand side;
-   * in other words, if the writing happens through a function like
+   *
+   * @note The conflict set returned by the user defined function passed as
+   * third argument needs to accurately describe <i>all</i> degrees of
+   * freedom for which anything is written into the matrix or right hand side.
+   * In other words, if the writing happens through a function like
    * ConstraintMatrix::copy_local_to_global(), then the set of conflict indices
    * must actually contain not only the degrees of freedom on the current
    * cell, but also those they are linked to by constraints such as hanging
diff --git a/deal.II/include/deal.II/base/work_stream.h b/deal.II/include/deal.II/base/work_stream.h
index 4feb5bb0f3..61731df318 100644
--- a/deal.II/include/deal.II/base/work_stream.h
+++ b/deal.II/include/deal.II/base/work_stream.h
@@ -1128,10 +1128,11 @@ namespace WorkStream
 
 
   /**
-   * This is the main function of the WorkStream concept, doing work as
-   * described in the introduction to this namespace.
+   * This is one of two main functions of the WorkStream concept, doing work as
+   * described in the introduction to this namespace. It corresponds to
+   * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth.
    *
-   * This is the function that can be used for worker and copier objects that
+   * This function that can be used for worker and copier objects that
    * are either pointers to non-member functions or objects that allow to be
    * called with an operator(), for example objects created by std::bind.
    *
@@ -1239,6 +1240,39 @@ namespace WorkStream
   }
 
 
+  /**
+   * This is one of two main functions of the WorkStream concept, doing work as
+   * described in the introduction to this namespace. It corresponds to
+   * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth.
+   * As such, it takes not a range of iterators described by a begin
+   * and end iterator, but a "colored" graph of iterators where each
+   * color represents cells for which writing the cell contributions into
+   * the global object does not conflict (in other words, these cells
+   * are not neighbors). Each "color" is represented by std::vectors of cells.
+   * The first argument to this function, a set of sets of cells (which are
+   * represent as a vector of vectors, for efficiency), is typically
+   * constructed by calling GraphColoring::make_graph_coloring().
+   *
+   * This function that can be used for worker and copier objects that
+   * are either pointers to non-member functions or objects that allow to be
+   * called with an operator(), for example objects created by std::bind.
+   *
+   * The two data types <tt>ScratchData</tt> and <tt>CopyData</tt> need to
+   * have a working copy constructor. <tt>ScratchData</tt> is only used in the
+   * <tt>worker</tt> function, while <tt>CopyData</tt> is the object passed
+   * from the <tt>worker</tt> to the <tt>copier</tt>.
+   *
+   * The @p queue_length argument indicates the number of items that can be
+   * live at any given time. Each item consists of @p chunk_size elements of
+   * the input stream that will be worked on by the worker and copier
+   * functions one after the other on the same thread.
+   *
+   * @note If your data objects are large, or their constructors are
+   * expensive, it is helpful to keep in mind that <tt>queue_length</tt>
+   * copies of the <tt>ScratchData</tt> object and
+   * <tt>queue_length*chunk_size</tt> copies of the <tt>CopyData</tt> object
+   * are generated.
+   */
   template <typename Worker,
            typename Copier,
            typename Iterator,
@@ -1324,8 +1358,10 @@ namespace WorkStream
 
 
   /**
-   * This is the main function of the WorkStream concept, doing work as
-   * described in the introduction to this namespace.
+   * This is a variant of one of the two main functions of the WorkStream
+   * concept, doing work as described in the introduction to this namespace.
+   * It corresponds to implementation 2 of the paper by Turcksin, Kronbichler
+   * and Bangerth.
    *
    * This is the function that can be used for worker and copier functions
    * that are member functions of a class.
-- 
2.39.5