]> https://gitweb.dealii.org/ - dealii.git/commitdiff
documentation improved for doxygen
authorGuido Kanschat <dr.guido.kanschat@gmail.com>
Sun, 1 Feb 2004 22:36:43 +0000 (22:36 +0000)
committerGuido Kanschat <dr.guido.kanschat@gmail.com>
Sun, 1 Feb 2004 22:36:43 +0000 (22:36 +0000)
git-svn-id: https://svn.dealii.org/trunk@8380 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/grid/tria_accessor.h
deal.II/deal.II/include/grid/tria_iterator.h
deal.II/deal.II/include/grid/tria_iterator_base.h

index 48aa97049bfa91df21df90abd4b25fbb2aa4a7f4..2d7ab14f773fd3771526239d76ae269dbbb70398 100644 (file)
@@ -42,8 +42,6 @@ namespace std
   struct pair;
 }
 
-
-
 // note: the file tria_accessor.templates.h is included at the end of
 // this file.  this includes a lot of templates. originally, this was
 // only done in debug mode, but led to cyclic reduction problems and
@@ -51,15 +49,57 @@ namespace std
 
 
 /**
- *   Implements the accessor class descibed in the documentation of
- *   the iterator classes (see @ref{TriaRawIterator}.
+ * Implements the accessor class used by TriaRawIterator and derived
+ * classes.
  *
- *   This class offers only the basic functionality (stores the necessary
- *   data members, offers comparison operators and the like), but has no
- *   functionality to actually dereference data. This is done in the derived
- *   classes.
+ * This class offers only the basic functionality erquired by the
+ * iterators (stores the necessary data members, offers comparison
+ * operators and the like), but has no functionality to actually
+ * dereference data. This is done in the derived classes.
  *
- *   @author Wolfgang Bangerth, 1998
+ * @section TAInternals Internals
+ *   
+ * There is a representation of past-the-end-pointers, denoted by
+ * special values of the member variables #present_level and
+ * #present_index: If #present_level>=0 and #present_index>=0, then
+ * the object is valid (there is no check whether the triangulation
+ * really has that many levels or that many cells on the present level
+ * when we investigate the state of an iterator; however, in many
+ * places where an iterator is dereferenced we make this check); if
+ * #present_level==-1 and #present_index==-1, then the iterator points
+ * past the end; in all other cases, the iterator is considered
+ * invalid.  You can check this by calling the state() function.
+ *
+ * An iterator is also invalid, if the pointer pointing to the
+ * Triangulation object is invalid or zero.
+ *
+ * Finally, an iterator is invalid, if the element pointed to by
+ * #present_level and #present_index is not used, i.e. if the
+ * <tt>used</tt> flag is set to false.
+ *
+ * The last two checks are not made in state() since both cases should
+ * only occur upon unitialized construction through <tt>memcpy</tt>
+ * and the like (the parent triangulation can only be set upon
+ * construction). If an iterator is constructed empty through the
+ * empty constructor, it sets #present_level==-2 and
+ * #present_index==-2. Thus, the iterator is invalid anyway,
+ * regardless of the state of the triangulation pointer and the state
+ * of the element pointed to.
+ *
+ * Past-the-end iterators may also be used to compare an iterator with
+ * the before-the-start value, when running backwards. There is no
+ * distiction between the iterators pointing past the two ends of a
+ * vector.
+ *   
+ * Defining only one value to be past-the-end and making all other
+ * values invalid provides a second track of security: if we should
+ * have forgotten a check in the library when an iterator is
+ * incremented or decremented, we automatically convert the iterator
+ * from the allowed state "past-the-end" to the disallowed state
+ * "invalid" which increases the chance that somehwen earlier than for
+ * past-the-end iterators an exception is raised.
+ *
+ * @author Wolfgang Bangerth, 1998
  */
 template <int dim>
 class TriaAccessor
@@ -1266,21 +1306,22 @@ class TriaObjectAccessor<2, dim> :  public TriaAccessor<dim>
     void set (const Quad &q) const;
     
                                     /**
-                                     *  Return index of vertex @p{i=0
-                                     *  through 3} of a quad. The
-                                     *  @p{i}th vertex is the common
-                                     *  one of line @p{i} and
-                                     *  @p{(i+3)%4}. See also the
-                                     *  introduced convention
-                                     *  (@ref{Triangulation}).
+                                     * Return index of a vertex of a
+                                     * quad in the internal data
+                                     * structure of a Triangulation.
                                      *
-                                     *  Note that the returned value is only
-                                     *  the index of the geometrical
-                                     *  vertex. It has nothing to do with
-                                     *  possible degrees of freedom
-                                     *  associated with it. For this, see the
-                                     *  @p{DoFAccessor::vertex_dof_index}
-                                     *  functions.
+                                     * For local numbering of the
+                                     * vertices, see the page on
+                                     * Geometry.
+                                     *
+                                     * @attention The value returned
+                                     * is only the index of the
+                                     * geometrical vertex. It has
+                                     * nothing to do with possible
+                                     * degrees of freedom associated
+                                     * with it. For this, see the
+                                     * DoFAccessor::vertex_dof_index
+                                     * functions.
                                      */ 
     int vertex_index (const unsigned int i) const;
 
@@ -1762,13 +1803,12 @@ class TriaObjectAccessor<3, dim> :  public TriaAccessor<dim>
     void set (const Hexahedron &h) const;
     
                                     /**
-                                     *  Return index of vertex @p{i=0
-                                     *  through 7} of a hex. The
-                                     *  convention regarding the
-                                     *  numbering of vertices is laid
-                                     *  down in the documentation of
-                                     *  the @ref{Triangulation}
-                                     *  class.
+                                     *  Return index of a vertex of a hex in the internal structures of Triangulation.
+                                     *
+                                     * For local numbering of the
+                                     * vertices, see the page on
+                                     * Geometry.
+                                     *
                                      *
                                      *  Note that the returned value is only
                                      *  the index of the geometrical
index 2808d978a557fa16ef4f849bd08116a5abbb6664..09c33c4af191d99b2f52d81674c498769c3d51c8 100644 (file)
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -42,193 +42,140 @@ template <int dim> class Triangulation;
 
 
 /**
- *   This class implements an iterator, analogous to those of the standard
- *   template library (STL). It fulfills the requirements of a bidirectional iterator.
- *   See the C++ documentation for further details of iterator specification and
- *   usage. In addition to the STL
- *   iterators an iterator of this class provides a @p{->} operator, i.e. you can
- *   write statements like @p{i->set_refine_flag ();}.
- *   
- *   @em{Note:} Please read the documentation about the prefix and the
- *   postfix @p{++} operators in this and the derived classes!
- *   
- *   @sect3{Purpose}
+ * This class implements an iterator, analogous to those of the
+ * standard template library (STL). It fulfills the requirements of a
+ * bidirectional iterator.  See the C++ documentation for further
+ * details of iterator specification and usage.
+ *
  *
- *   @p{iterators} are used whenever a loop over all lines, quads, cells etc.
- *   is to be performed. These loops can then be coded like this:
- *   @begin{verbatim}
- *     cell_iterator i   = tria.begin();
- *     cell_iterator end = tria.end();
- *     for (; i!=end; ++i)
- *       if (cell->at_boundary())
- *         cell->set_refine_flag();
- *   @end{verbatim}
- *   Note the usage of @p{++i} instead of @p{i++} since this does not involve
- *   temporaries and copying. You should also really use a fixed value
- *   @p{end} rather than coding @p{for (; i!=tria.end(); ++i)}, since
- *   the creation and copying of these iterators is rather expensive
- *   compared to normal pointers.
+ * In addition to the STL
+ * iterators an iterator of this class provides a <tt>-@></tt>
+ * operator, i.e. you can write statements like
+ * @code
+ * i->set_refine_flag ();
+ * @endcode
  *   
- *   The objects pointed to by iterators are @ref{TriangulationLevel<1>}@p{::LinesData},
- *   @ref{TriangulationLevel<2>}@p{::LinesData}
- *   and @ref{TriangulationLevel<2>}@p{::QuadsData}. To chose which of those, the
- *   template parameter @p{Pointee} is used.
+ * Iterators are used whenever a loop over all lines, quads, cells
+ * etc.  is to be performed. These loops can then be coded like this:
+ * @code
+ *   cell_iterator i   = tria.begin();
+ *   cell_iterator end = tria.end();
+ *   for (; i!=end; ++i)
+ *     if (cell->at_boundary())
+ *       cell->set_refine_flag();
+ * @endcode
  *
- *   Since the names as is are quite unhandy, the @ref{Triangulation} class which
- *   uses these iterators declares typedef'd versions. See there for more
- *   information.
+ * Note the usage of <tt>++i</tt> instead of <tt>i++</tt> since this
+ * does not involve temporaries and copying. It is recommended to use
+ * a fixed value <tt>end</tt> inside the loop instead of
+ * <tt>tria.end()</tt>, since the creation and copying of these
+ * iterators is rather expensive compared to normal pointers.
+ *   
+ * The objects pointed to are accessors, derived from
+ * TriaAccessor. Which kind of accessor is determined by the template
+ * argument <em>Accessor</em>. These accessors are not so much data
+ * structures as they are a collection of functions providing access
+ * to the data stored in Tringulation or DoFHandler objects. Using
+ * these accessors, the structure of these classes is hidden from the
+ * application program.
  *
- *   The objects pointed to are, as mentioned, @ref{LinesData} etc. To be
- *   more exact, when dereferencing an iterator, you do not get a @ref{LineData}
- *   object (or the like, but we will assume that you have a @p{line_iterator}
- *   in the following), but a @em{virtual} object (called @em{accessor}) which
- *   behaves as if it stored the data of a line. It does not contain any data
- *   itself, but provides functions to manipulate the data of the line it
- *   stands for.
+ * @section TIDiff Which iterator to use when
  *
- *   Since the data of one line is splitted to
- *   several arrays (@p{lines}, @p{children} and @p{used}) for performance reasons
- *   rather than keeping all information in a @ref{Line} struct, access through
- *   an accessor is usually much simpler than handling the exact data structure
- *   and also less error prone since the data structure itself can be changed
- *   in an arbitrary way while the only pieces of code which access these
- *   data structures are the accessors.
+ * @attention Application programs will rarely use TriaRawIterator,
+ * but rather one of the derived classes TriaIterator or
+ * TriaActiveIterator.
  *
- *   On the other hand, iterators are not much slower than operating directly
- *   on the data structures, since they perform the loops that you had
- *   to handcode yourself anyway. Most iterator and accessor functions are
- *   inlined. 
+ * <ul> <li> TriaRawIterator objects point to lines, cells, etc in the
+ * lists whether they are used or not (in the vectors, also
+ * <i>dead</i> objects are stored, since deletion in vectors is
+ * expensive and we also do not want to destroy the ordering induced
+ * by the numbering in the vectors). Therefore not all raw iterators
+ * point to valid objects.
  *
- *   The main functionality of iterators, however, resides in the @p{++} and
- *   @p{--} operators. These move the iterator forward or backward just as if
- *   it were a pointer into an array. Here, this operation is not so easy,
- *   since it may include skipping some elements and the transition between
- *   the triangulation levels. This is completely hidden from the user, though
- *   you can still create an iterator pointing to an arbitrary element.
- *   Actually, the operation of moving iterators back and forth is not done in
- *   the iterator classes, but rather in the accessor classes. Since these are
- *   passed as template arguments, you can write your own versions here to add
- *   more functionality.
+ * <li> The derived class TriaIterator selects the valid cells, that
+ * is, cells used somewhere in the triangulation hierarchy.
  *
- *   Furthermore, the iterators decribed here satisfy the requirement of
- *   input and bidirectional iterators as stated by the C++ standard and
- *   the STL documentation. It is therefore possible to use the functions
- *   from the @em{algorithm section} of the C++ standard, e.g. @p{count_if}
- *   (see the documentation for @ref{Triangulation} for an example) and
- *   several others.
+ * <li> TriaActiveIterator objects which only loop over active cells.
  *   
+ * @section TIPurpose Purpose
  *
- *   @sect3{Differences between the classes in this inheritance tree}
+ * Iterators are not much slower than operating directly on the data
+ * structures, since they perform the loops that you had to handcode
+ * yourself anyway. Most iterator and accessor functions are inlined.
  *
- *   @p{TriaRawIterator} objects point to lines, cells, etc in
- *   the lists whether they are used or not (in the vectors, also @em{dead}
- *   objects are stored, since deletion in vectors is expensive and we
- *   also do not want to destroy the ordering induced by the numbering
- *   in the vectors). Therefore not all raw iterators point to valid objects.
- *   
- *   There are two derived versions of this class: @ref{TriaIterator}
- *   objects, which only loop over used (valid) cells and
- *   @p{TriaActiveIterator} objects
- *   which only loop over active cells (not refined).
+ * The main functionality of iterators, resides in the <tt>++</tt> and
+ * <tt>--</tt> operators. These move the iterator forward or backward
+ * just as if it were a pointer into an array. Here, this operation is
+ * not so easy, since it may include skipping some elements and the
+ * transition between the triangulation levels. This is completely
+ * hidden from the user, though you can still create an iterator
+ * pointing to an arbitrary element.  Actually, the operation of
+ * moving iterators back and forth is not done in the iterator
+ * classes, but rather in the accessor classes. Since these are passed
+ * as template arguments, you can write your own versions here to add
+ * more functionality.
  *
+ * Furthermore, the iterators decribed here satisfy the requirement of
+ * input and bidirectional iterators as stated by the C++ standard and
+ * the STL documentation. It is therefore possible to use the
+ * functions from the algorithm section of the C++ standard,
+ * e.g. <em>count_if</em> (see the documentation for Triangulation for
+ * an example) and several others.
  *   
- *   @sect3{Implementation}
+ * @section TIImplementation Implementation
  *
- *   In principle, the Iterator class does not have much functionality. It
- *   only becomes useful when assigned an @p{Accessor} (the second template
- *   parameter), which really does the access to data. An @p{Accessor} has to
- *   fulfil some requirements:
- *   @begin{itemize}
- *     @item It must have two members named @p{present_level} and @p{present_index}
- *       storing the address of the element in the triangulation presently
- *       pointed to. Furthermore, the three @p{Tria{Raw| |Active}Iterator} classes
- *       have to be friends to the accessor or these data members must be public.
- *     @item It must have a constructor which takes 1. a @p{Triangulation<dim>*},
- *       2. and 3. and integer, denoting the initial level and index.
- *     @item For the @p{TriaIterator} and the @p{TriaActiveIterator} class, it must
- *       have a member function @p{bool used()}, for the latter a member function
- *       @p{bool active()}.
- *     @item It must have void operators @p{++} and @p{--}.
- *     @item It must declare a local @p{typedef} @p{AccessorData} which states
- *       the data type the accessor expects to get passed as fourth constructor
- *       argument. By declaring a local data type, the respective iterator
- *       class may type-safely enforce that data type to be one of its own
- *       constructor argument types. If an accessor class does not need
- *       additional data, this type shall be @p{void}.
- *   @end{itemize}
- *   Then the iterator is able to do what it is supposed to. All of the necessary
- *   functions are implemented in the @p{Accessor} base class, but you may write
- *   your own version (non-virtual, since we use templates) to add functionality.
+ * The iterator class itself does not have much functionality. It only
+ * becomes useful when assigned an Accessor (the second template
+ * parameter), which really does the access to data. An Accessor
+ * has to fulfil some requirements:
  *
- *   There is a standard implementation, using classes which are derived from
- *   @ref{TriaAccessor}. These classes point to @ref{Line}s, @ref{Quad}s and the like.
- *   For advanced use of the iterator classes, derive classes from
- *   @p{{Line|Quad|Cell}Accessor} which also dereference data structures in other
- *   objects, e.g. in a finite element context. An iterator with such an accessor
- *   then simultaneously points to (for example) a cell in the triangulation and
- *   the data stored on it in the finite element class.
+ * <ul> <li> It must have two members named <tt>present_level</tt> and
+ * <tt>present_index</tt> storing the address of the element in the
+ * triangulation presently pointed to. These data have to be
+ * accessible by all triangulation iterators listed above.
  *
- *   Derived accessor classes may need additional data (e.g. the @ref{DoFAccessor}
- *   needs a pointer to the @ref{DoFHandler} to work on). This data can be
- *   set upon construction through the last argument of the constructors.
- *   The data type of this additional data is given by the local data type
- *   @ref{AccessorData} explained above. The iterator classes take a pointer to
- *   an object of that data type; by default, this parameter equals the
- *   @p{NULL} pointer.
- *   
- *   
- *   @sect3{Warning}
+ * <li> It must have a constructor which takes a Triangulation* and
+ * two unsigned integers, denoting the initial level and index, as
+ * well as a data object depending on its type.
  *
- *   It seems impossible to preserve @p{const}ness of a triangulation through
- *   iterator usage. Thus, if you declare pointers to a @p{const} triangulation
- *   object, you should be well aware that you might involuntarily alter the
- *   data stored in the triangulation.
+ * <li> For the TriaIterator and the TriaActiveIterator class, it must
+ * have a member function <tt>bool used()</tt>, for the latter a
+ * member function <tt>bool active()</tt>.
  *
+ * <li> It must have void operators <tt>++</tt> and <tt>--</tt>.
  *
- *   @sect3{Internals}
- *   
- *   There is a representation of past-the-end-pointers, denoted by special
- *   values of the member variables @p{present_level} and @p{present_index}:
- *   If @p{present_level>=0} and @p{present_index>=0}, then the object is valid
- *   (there is no check whether the triangulation really has that
- *   many levels or that many cells on the present level when we investigate
- *   the state of an iterator; however, in many places where an iterator is
- *   dereferenced we make this check);
- *   if @p{present_level==-1} and @p{present_index==-1}, then the iterator points
- *   past the end; in all other cases, the iterator is considered invalid.
- *   You can check this by calling the @p{state()} function.
+ * <li> It must declare a local <tt>typedef AccessorData</tt> which
+ * states the data type the accessor expects to get passed as fourth
+ * constructor argument. By declaring a local data type, the
+ * respective iterator class may type-safely enforce that data type to
+ * be one of its own constructor argument types. If an accessor class
+ * does not need additional data, this type shall be <tt>void</tt>.
+ * </ul>
  *
- *   An iterator is also invalid, if the pointer pointing to the @ref{Triangulation}
- *   object is invalid or zero.
+ * Then the iterator is able to do what it is supposed to. All of the
+ * necessary functions are implemented in the <tt>Accessor</tt> base
+ * class, but you may write your own version (non-virtual, since we
+ * use templates) to add functionality.
  *
- *   Finally, an iterator is invalid, if the element pointed to by
- *   @p{present_level} and @p{present_index} is not used, i.e. if the @p{used}
- *   flag is set to false.
+ * The accessors provided by the library are distributed in three
+ * groups, determined by whether they access the data of
+ * Triangulation, DoFHandler or MGDoFHandler. They are derived from
+ * TriaObjectAccessor, DoFObjectAccessor and MGDoFObjectAccessor,
+ * respectively. In each group, there is an accessor to cells, which
+ * have more functionality.
+ * 
+ * @attention It seems impossible to preserve constness of a
+ * triangulation through iterator usage. Thus, if you declare pointers
+ * to a <tt>const</tt> triangulation object, you should be well aware
+ * that you might involuntarily alter the data stored in the
+ * triangulation.
  *
- *   The last two checks are not made in @p{state()} since both cases should only
- *   occur upon unitialized construction through @p{memcpy} and the like (the
- *   parent triangulation can only be set upon construction). If
- *   an iterator is constructed empty through the empty constructor,
- *   @p{present_level==-2} and @p{present_index==-2}. Thus, the iterator is
- *   invalid anyway, regardless of the state of the triangulation pointer
- *   and the state of the element pointed to.
+ * @note More information on valid and invalid iterators can be found
+ * in the documentation of TriaAccessor, where the iterator states are
+ * checked and implemented.
  *
- *   Past-the-end iterators may also be used to compare an iterator with the
- *   @em{before-the-start} value, when running backwards. There is no
- *   distiction between the iterators pointing past the two ends of a vector.
- *   
- *   By defining only one value to be past-the-end and making all other values
- *   invalid porvides a second track of security: if we should have forgotten
- *   a check in the library when an iterator is incremented or decremented,
- *   we automatically convert the iterator from the allowed state "past-the-end"
- *   to the disallowed state "invalid" which increases the chance that somehwen
- *   earlier than for past-the-end iterators an exception is raised.
- *
- *   @ref Triangulation
- *   @ref TriaDimensionInfo<1>
- *   @ref TriaDimensionInfo<2>
- *   @ref TriaDimensionInfo<3>
- *   @author Wolfgang Bangerth, 1998
+ * @author Wolfgang Bangerth, 1998
+ * @author documentation update Guido Kanschat, 2004
  */
 template <int dim, typename Accessor>
 class TriaRawIterator :
index a040156d52b5db7d8e650a081f52cfea9ae903ed..41746f1c2209575af8d4eaedb039741c39b19b7e 100644 (file)
@@ -2,7 +2,7 @@
 //    $Id$
 //    Version: $Name$
 //
-//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003 by the deal.II authors
+//    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004 by the deal.II authors
 //
 //    This file is subject to QPL and may not be  distributed
 //    without copyright and license information. Please refer
@@ -30,8 +30,11 @@ namespace IteratorState
  */
   enum IteratorStates
   {
+                                        /// Iterator points to a valid object
        valid,
+                                        /// Iterator reached end of container
        past_the_end,
+                                        /// Iterator is invalid, probably due to an error
        invalid
   };
 }

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.