From 09423a1ed3d23ac0c221af039841f508cedcc792 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Thu, 12 Jun 2014 05:38:03 +0000 Subject: [PATCH] Clarify documentation in a number of places. git-svn-id: https://svn.dealii.org/trunk@33038 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/include/deal.II/grid/cell_id.h | 29 +++++++++++++++----- deal.II/include/deal.II/grid/tria_accessor.h | 26 ++++++++++-------- 2 files changed, 37 insertions(+), 18 deletions(-) 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 within the + * triangulation stored on each of the processors 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; -- 2.39.5