From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Thu, 12 Jun 2014 05:38:03 +0000 (+0000)
Subject: Clarify documentation in a number of places.
X-Git-Tag: v8.2.0-rc1~400
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=09423a1ed3d23ac0c221af039841f508cedcc792;p=dealii.git

Clarify documentation in a number of places.

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

diff --git a/deal.II/include/deal.II/grid/cell_id.h b/deal.II/include/deal.II/grid/cell_id.h
index 2d671ea4d3..ada26f77d9 100644
--- a/deal.II/include/deal.II/grid/cell_id.h
+++ b/deal.II/include/deal.II/grid/cell_id.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 1998 - 2013 by the deal.II authors
+// Copyright (C) 1998 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -27,13 +27,28 @@ DEAL_II_NAMESPACE_OPEN
 
 
 /**
- * A class to represent a unique ID for a cell in a Triangulation.
- * This class stores the index of the coarse cell together with the
- * information on how to reach the cell from that coarse cell (which
- * child index to take on each level). The internal representation
- * is not exposed on purpose.
+ * A class to represent a unique ID for a cell in a Triangulation.  This class
+ * stores the index of the coarse cell from which a cell is descendant,
+ * together with information on how to reach the cell from that coarse cell
+ * (i.e., which child index to take on each level when moving from one cell to
+ * its children). The important point about this class is that an object of
+ * the current class uniquely identifies a cell in triangulation, and it even
+ * does so in the context of objects of type
+ * parallel::distributed::Triangulation where the local portion of a mesh may
+ * not store all cells. For example, the CellId computed for a ghost cell on
+ * one processor will be exactly the same as the CellId computed for the very
+ * same cell on the processor that actually owns the cell, although the level
+ * and index of the iterators pointing to that cell <i>within the
+ * triangulation stored on each of the processors</i> may (and in general
+ * will) be different. In other words, CellId provides the tool with which it
+ * is possible to uniquely identify cells in a parallel triangulation, and
+ * consequently makes it possible to exchange data between processors tied to
+ * individual cells.
  *
- * TODO: does it make sense to implement a more efficient representation
+ * @note How this data is internally represented is not of importance (and not
+ * exposed on purpose).
+ *
+ * @todo Does it make sense to implement a more efficient representation
  * (internally and/or as a string)? If yes, something like a 64bit int
  * as in p4est would be a good option.
  */
diff --git a/deal.II/include/deal.II/grid/tria_accessor.h b/deal.II/include/deal.II/grid/tria_accessor.h
index f4c1c91dba..91429d8b16 100644
--- a/deal.II/include/deal.II/grid/tria_accessor.h
+++ b/deal.II/include/deal.II/grid/tria_accessor.h
@@ -2860,13 +2860,11 @@ public:
   bool direction_flag () const;
 
   /**
-   *  Index of the parent of this cell.
-   *  The level of the parent is one
-   *  lower than that of the
-   *  present cell, if the parent
-   *  of a cell is accessed. If the
-   *  parent does not exist (i.e., if the object is at the coarsest level of
-   *  the mesh hierarchy), an exception is generated.
+   *  Index of the parent of this cell within the level of the triangulation
+   *  to which the parent cell belongs. The level of the parent is of course
+   *  one lower than that of the present cell. If the parent does not exist
+   *  (i.e., if the object is at the coarsest level of the mesh hierarchy), an
+   *  exception is generated.
    */
   int parent_index () const;
 
@@ -3050,10 +3048,16 @@ public:
 
   /**
    * Return a unique ID for the current cell. This ID is constructed from the
-   * path in the hierarchy from the coarse father cell and works correctly
-   * in parallel computations.
-   *
-   * Note: This operation takes O(log(level)) time.
+   * path in the hierarchy from the coarse father cell and works correctly in
+   * parallel computations using objects of type
+   * parallel::distributed::Triangulation. This function is therefore useful
+   * in providing a unique identifier for cells (active or not) that also
+   * works for parallel triangulations. See the documentation of the CellId
+   * class for more information.
+   *
+   * @note This operation takes O(level) time to compute. In most practicaly
+   * cases, the number of levels of a triangulation will depend
+   * logarithmically on the number of cells in the triangulation.
    */
   CellId id() const;