more documentation on iterators

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

diff --git a/deal.II/deal.II/include/dofs/dof_accessor.h b/deal.II/deal.II/include/dofs/dof_accessor.h
index 903ac25a6b8a9e0ee10c90b32f409f981fad361f..ec6998e4b65d7bb9ce645574b290becd3a5bd6cd 100644 (file)
--- a/deal.II/deal.II/include/dofs/dof_accessor.h
+++ b/deal.II/deal.II/include/dofs/dof_accessor.h
@@ -63,6 +63,7 @@ template <int dim>              class DoFObjectAccessor<3, dim>;
  * the #Assert macro is switched on.
  *
  * @ingroup dofs
+ * @ingroup Accessors 
  * @author Wolfgang Bangerth, 1998
  */
 template <int dim>
@@ -169,6 +170,7 @@ class DoFAccessor
  * object under consideration has full dimension, i.e. constitutes a cell.
  *
  * @ingroup dofs
+ * @ingroup Accessors 
  * @author Wolfgang Bangerth, 1999
  */
 template <int celldim, int dim>
@@ -196,6 +198,7 @@ class DoFObjectAccessor_Inheritance
  * object under consideration has full dimension, i.e. constitutes a cell.
  *
  * @ingroup dofs
+ * @ingroup Accessors 
  * @author Wolfgang Bangerth, 1999
  */
 template <int dim>
@@ -250,6 +253,9 @@ class DoFObjectAccessor_Inheritance<dim,dim>
  * 
  * (Internal: inheritance is necessary for the general template due to
  * a compiler error.)
+ *
+ * @ingroup dofs 
+ * @ingroup Accessors 
  */
 template<int celldim, int dim>
 class DoFObjectAccessor : public DoFAccessor<dim>,
@@ -459,6 +465,7 @@ class DoFObjectAccessor : public DoFAccessor<dim>,
 
 /**
  * Closure class.
+ * @ingroup dofs
  */
 template<int dim>
 class DoFObjectAccessor<0, dim> : public DoFAccessor<dim>,

diff --git a/deal.II/deal.II/include/grid/filtered_iterator.h b/deal.II/deal.II/include/grid/filtered_iterator.h
index 834bf16019a0a6fd4bdcf2d3d8a9c3cc34bfd6ad..501b755e03167313fa34f8d92d71b29cad644ec3 100644 (file)
--- a/deal.II/deal.II/include/grid/filtered_iterator.h
+++ b/deal.II/deal.II/include/grid/filtered_iterator.h
@@ -210,13 +210,17 @@ namespace IteratorFilters
  *
  * The object that represent the condition an iterator has to satisfy
  * only have to provide an interface that allows to call the
- * evaluation operator, i.e. <tt>operator()</tt>. This includes function
- * pointers as well as classes that implement an <tt>operator ()</tt>.
+ * evaluation operator, i.e. <tt>bool operator() (const
+ * BaseIterator&)</tt>. This includes function pointers as well as
+ * classes that implement an <tt>bool operator ()(const
+ * BaseIterator&)</tt>. Then, the FilteredIterator will skip all
+ * objects where the return value of this function is <tt>false</tt>.
+ *
  *
  * An example of a simple valid predicate is the following: given the function
  * @code
- *   template <typename Iterator>
- *   bool level_equal_to_3 (const Iterator c)
+ *   template <typename BIterator>
+ *   bool level_equal_to_3 (const BIterator& c)
  *   {
  *     return (static_cast<unsigned int>(c->level()) == 3);
  *   };
@@ -229,8 +233,8 @@ namespace IteratorFilters
  *
  * Likewise, given the following binary function
  * @code
- *   template <typename Iterator>
- *   bool level_equal_to (const Iterator     c,
+ *   template <typename BIterator>
+ *   bool level_equal_to (const BIterator&     c,
  *                        const unsigned int level)
  *   {
  *     return (static_cast<unsigned int>(c->level()) == level);
@@ -372,6 +376,7 @@ namespace IteratorFilters
  * and its value does not depend on the filter.
  *
  * @ingroup grid
+ * @ingroup Iterators
  * @author Wolfgang Bangerth, 2002
  */
 template <typename BaseIterator>

diff --git a/deal.II/deal.II/include/grid/tria_accessor.h b/deal.II/deal.II/include/grid/tria_accessor.h
index 735cc2276d01d5d2240466e4a8c27da572aa68f0..89bd71f23596b71944d658e76af2f5346a227abf 100644 (file)
--- a/deal.II/deal.II/include/grid/tria_accessor.h
+++ b/deal.II/deal.II/include/grid/tria_accessor.h
@@ -99,6 +99,8 @@ namespace std
  * "invalid" which increases the chance that somehwen earlier than for
  * past-the-end iterators an exception is raised.
  *
+ * @ingroup grid
+ * @ingroup Accessors
  * @author Wolfgang Bangerth, 1998
  */
 template <int dim>
@@ -225,22 +227,22 @@ class TriaAccessor
                                      */
                                     /*@{*/
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcCellNotUsed);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException1 (ExcInvalidNeighbor,
                    int,
                    << "Neighbor indices must be between 0 and 2^dim-1, but "
                    << "yours was " << arg1);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcUnusedCellAsChild);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException1 (ExcCantSetChildren,
                    int,
@@ -248,31 +250,31 @@ class TriaAccessor
                    << "children, or clear it. The given "
                    << "index was " << arg1 << " (-1 means: clear children)");
                                     /**
-                                     * Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcUnusedCellAsNeighbor);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcUncaughtCase);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcDereferenceInvalidObject);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcNotUsefulForThisDimension);
                                     /**
-                                     * Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcCantCompareIterators);
                                     /**
-                                     * Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcNeighborIsCoarser);
                                     /**
-                                     * Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcNeighborIsNotCoarser);
                                     /*@}*/
@@ -313,6 +315,8 @@ class TriaAccessor
  * access, we nevertheless document all functions of the specialized
  * classes here as well. However, they are not implemented.
  *
+ * @ingroup grid
+ * @ingroup Accessors
  * @author Wolfgang Bangerth, Guido Kanschat, 1999
  */
 template <int celldim, int dim>
@@ -812,6 +816,8 @@ class TriaObjectAccessor :  public TriaAccessor<dim>
 /**
  * Closure class to stop induction of classes. Should never be called
  * and thus produces an error when created.
+ *
+ * @ingroup grid
  */
 template<int dim>
 class TriaObjectAccessor<0, dim> : public TriaAccessor<dim>
@@ -848,6 +854,7 @@ class TriaObjectAccessor<0, dim> : public TriaAccessor<dim>
  *   also a cell and thus has much more functionality than in other
  *   dimensions.
  *
+ * @ingroup grid
  *   @author Wolfgang Bangerth, 1998
  */
 template <int dim>
@@ -1300,6 +1307,7 @@ class TriaObjectAccessor<1, dim> :  public TriaAccessor<dim>
  *   two space dimension, in which case a quad is also a cell and thus
  *   has much more functionality than in other dimensions.
  *
+ * @ingroup grid
  *   @author Wolfgang Bangerth, 1998
  */
 template <int dim>
@@ -1805,6 +1813,7 @@ class TriaObjectAccessor<2, dim> :  public TriaAccessor<dim>
  *   hexs in three space dimension, in which case a hex is also a cell
  *   and thus has much more functionality than in other dimensions.
  *
+ * @ingroup grid
  *   @author Wolfgang Bangerth, 1998
  */
 template <int dim>
@@ -2335,6 +2344,8 @@ class TriaObjectAccessor<3, dim> :  public TriaAccessor<dim>
  * have neighbors, they have the possibility to check whether they are
  * at the boundary etc. This class offers access to all this data.
  *
+ * @ingroup grid
+ * @ingroup Accessors
  * @author Wolfgang Bangerth, 1998, 1999, 2000
  */
 template <int dim>
@@ -2573,29 +2584,36 @@ class CellAccessor :  public TriaObjectAccessor<dim,dim>
                                       * figure out which cell we want
                                       * to have.
                                       *
-                                      * This can lead to surprising results:
-                                      * if we are sitting on a cell and are
-                                      * asking for a cell behind subface @sf,
-                                      * then this means that we are
-                                      * considering the subface for the face
-                                      * in the natural direction for the
-                                      * present cell. However, if the face as
-                                      * seen from this cell has
+                                      * This can lead to surprising
+                                      * results: if we are sitting on
+                                      * a cell and are asking for a
+                                      * cell behind subface
+                                      * <tt>sf</tt>, then this means
+                                      * that we are considering the
+                                      * subface for the face in the
+                                      * natural direction for the
+                                      * present cell. However, if the
+                                      * face as seen from this cell
+                                      * has
                                       * <tt>face_orientation()==false</tt>,
-                                      * then the child of the face that
-                                      * separates the present cell from the
-                                      * neighboring cell's child is not
-                                      * necessarily the @p sf-th child of the
-                                      * face of this cell. This is so because
-                                      * the @p subface_no parameter to this
-                                      * function corresponds to the subface
-                                      * with respect to the intrinsic ordering
-                                      * of the present cell, whereas children
-                                      * of face iterators are computed with
-                                      * respect to the intrinsic ordering of
-                                      * faces; these two orderings are only
-                                      * identical if the face orientation is
-                                      * @p true, and reversed otherwise.
+                                      * then the child of the face
+                                      * that separates the present
+                                      * cell from the neighboring
+                                      * cell's child is not
+                                      * necessarily the @p sf-th child
+                                      * of the face of this cell. This
+                                      * is so because the @p
+                                      * subface_no parameter to this
+                                      * function corresponds to the
+                                      * subface with respect to the
+                                      * intrinsic ordering of the
+                                      * present cell, whereas children
+                                      * of face iterators are computed
+                                      * with respect to the intrinsic
+                                      * ordering of faces; these two
+                                      * orderings are only identical
+                                      * if the face orientation is @p
+                                      * true, and reversed otherwise.
                                       *
                                       * Fortunately, this is only very rarely
                                       * of concern, since one is usually only
@@ -2669,15 +2687,15 @@ class CellAccessor :  public TriaObjectAccessor<dim,dim>
     
     
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcRefineCellNotActive);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcCellFlaggedForRefinement);
                                     /**
-                                     *  Exception
+                                     * @ingroup Exceptions
                                      */
     DeclException0 (ExcCellFlaggedForCoarsening);
     

diff --git a/deal.II/deal.II/include/grid/tria_iterator.h b/deal.II/deal.II/include/grid/tria_iterator.h
index 5c3f35c1082b8db9af7fc2b50e9ab4e0b50ba310..cfad8d7035eaac14fa57504a57803ced016862ea 100644 (file)
--- a/deal.II/deal.II/include/grid/tria_iterator.h
+++ b/deal.II/deal.II/include/grid/tria_iterator.h
@@ -219,6 +219,7 @@ template <int dim> class Triangulation;
  * @ref TriaDimensionInfo<1>
  * @ref TriaDimensionInfo<2>
  * @ref TriaDimensionInfo<3>
+ * @ingroup Iterators
  * @author Wolfgang Bangerth, 1998
  * @author documentation update Guido Kanschat, 2004
  */
@@ -546,6 +547,8 @@ class TriaRawIterator :
 /**
  *   This specialization of TriaRawIterator provides access only to
  *   the <em>used</em> lines, quads, cells, etc.
+ *
+ * @ingroup Iterators
  */
 template <int dim, typename Accessor>
 class TriaIterator : public TriaRawIterator<dim,Accessor> 
@@ -694,6 +697,8 @@ class TriaIterator : public TriaRawIterator<dim,Accessor>
  *   <em>active</em> lines, quads, cells, etc. An active cell is a
  *   cell which is not refined and thus a cell on which calculations
  *   on the finest level are done.
+ *
+ * @ingroup Iterators
  */
 template <int dim, typename Accessor>
 class TriaActiveIterator : public TriaIterator<dim,Accessor>