Provide more context in the documentation and link to a paper in preparation.

git-svn-id: https://svn.dealii.org/trunk@31705 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h
index a4acb8b8c6ce7e928c106809f69a11ddcdb2e6f1..8117be9be15fe48814b1d6064a2bc2b0bb523608 100644 (file)
--- a/deal.II/doc/doxygen/headers/glossary.h
+++ b/deal.II/doc/doxygen/headers/glossary.h
@@ -1296,6 +1296,17 @@ Article{JK10,
  *   @note The usual warning about the missing type safety of @p void pointers are
  *   obviously in place here; responsibility for correctness of types etc
  *   lies entirely with the user of the pointer.
+ *
+ *
+ * <dt class="glossary">@anchor workstream_paper <b>%WorkStream paper</b></dt>
+ * <dd>The "%WorkStream paper" is a paper by B. Turcksin, M. Kronbichler and W. Bangerth
+ *   that discusses the design and implementation of WorkStream. WorkStream is, at its
+ *   core, a design pattern, i.e., something that is used over and over in finite element
+ *   codes and that can, consequently, be implemented generically. In particular, the
+ *   paper lays out the motivation for this pattern and then proposes different ways
+ *   of implementing it. It also compares the performance of different implementations.
+ *
+ *   The paper is currently in preparation.
  * </dd>
  *
  * </dl>

diff --git a/deal.II/include/deal.II/base/graph_coloring.h b/deal.II/include/deal.II/base/graph_coloring.h
index 86601c87b55db9b8ef0c81a50229551fb422a4ec..d8cc56d27aedbca059e53d19a911008ba3087626 100644 (file)
--- a/deal.II/include/deal.II/base/graph_coloring.h
+++ b/deal.II/include/deal.II/base/graph_coloring.h
@@ -491,6 +491,9 @@ namespace GraphColoring
    * conflict indicator sets have overlap will not be assigned to the same
    * color.
    *
+   * @note The algorithm used in this function is described in a paper by
+   * Turcksin, Kronbichler and Bangerth, see @ref workstream_paper .
+   *
    * @param[in] begin The first element of a range of iterators for which a
    *      coloring is sought.
    * @param[in] end The element past the end of the range of iterators.

diff --git a/deal.II/include/deal.II/base/work_stream.h b/deal.II/include/deal.II/base/work_stream.h
index 330afcf1ce273e95165abafe6e96a5c81bf67f7f..71cadb7536047195758305bf50cdd4a9f44f6756 100644 (file)
--- a/deal.II/include/deal.II/base/work_stream.h
+++ b/deal.II/include/deal.II/base/work_stream.h
@@ -125,9 +125,9 @@ DEAL_II_NAMESPACE_OPEN
  * are considered unused and may be re-used for the next invokation of
  * the worker function, on this or another thread.
  *
- * This class only really works in parallel when multithread mode was selected
- * during deal.II configuration. Otherwise it simply works on each item
- * sequentially.
+ * 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.
  *
  * @ingroup threads
  * @author Wolfgang Bangerth, 2007, 2008, 2009, 2013. Bruno Turcksin, 2013.
@@ -149,7 +149,7 @@ namespace WorkStream
      * A namespace for the implementation of details of the WorkStream pattern
      * and function. This namespace holds classes that deal with the second
      * implementation described in the paper by Turcksin, Kronbichler and
-     * Bangerth.
+     * Bangerth (see @ref workstream_paper).
      *
      * Even though this implementation is slower than the third implementation
      * discussed in that paper, we need to keep it around for two reasons:
@@ -693,7 +693,7 @@ namespace WorkStream
      * A namespace for the implementation of details of the WorkStream pattern
      * and function. This namespace holds classes that deal with the third
      * implementation described in the paper by Turcksin, Kronbichler and
-     * Bangerth.
+     * Bangerth (see @ref workstream_paper).
      */
     namespace Implementation3
     {
@@ -781,7 +781,8 @@ namespace WorkStream
            * Pointer to a thread local variable identifying the scratch
            * and copy data objects this thread will use. The same considerations
            * apply as documented in the Implementation2::IteratorRangeToItemStream
-           * class as well as in the paper by Turcksin, Kronbichler and Bangerth.
+           * class as well as in the paper by Turcksin, Kronbichler and Bangerth
+          * (see @ref workstream_paper).
            */
           Threads::ThreadLocalStorage<ScratchAndCopyDataList> *scratch_and_copy_data;
 
@@ -924,7 +925,7 @@ namespace WorkStream
          * copy data objects each thread will use. The same is true as
          * discussed for the implementation in the
          * Implementation2::IteratorRangeToItemStream class and the paper
-         * by Turcksin, Kronbichler and Bangerth.
+         * by Turcksin, Kronbichler and Bangerth (see @ref workstream_paper).
          */
         Threads::ThreadLocalStorage<typename ItemType::ScratchAndCopyDataList> thread_local_scratch_and_copy;
 
@@ -1144,7 +1145,8 @@ 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 2 of the paper by Turcksin, Kronbichler and Bangerth.
+   * implementation 2 of the paper by Turcksin, Kronbichler and Bangerth
+   * (see @ref workstream_paper).
    *
    * 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
@@ -1257,7 +1259,8 @@ 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.
+   * implementation 3 of the paper by Turcksin, Kronbichler and Bangerth,
+   * see @ref workstream_paper .
    * 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
@@ -1265,7 +1268,8 @@ namespace WorkStream
    * 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().
+   * constructed by calling GraphColoring::make_graph_coloring(). See there
+   * for more information.
    *
    * 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
@@ -1375,7 +1379,7 @@ namespace WorkStream
    * 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.
+   * and Bangerth (see @ref workstream_paper).
    *
    * This is the function that can be used for worker and copier functions
    * that are member functions of a class.