From aca4a04ae45ad30a2c232fa4f4971cc8ab804967 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Thu, 1 Nov 2018 10:16:18 -0600 Subject: [PATCH] Fix some commentary on iterators. --- include/deal.II/grid/tria_iterator.h | 67 ++++++++++++++++++---------- 1 file changed, 44 insertions(+), 23 deletions(-) diff --git a/include/deal.II/grid/tria_iterator.h b/include/deal.II/grid/tria_iterator.h index 240aef0339..02213018a9 100644 --- a/include/deal.II/grid/tria_iterator.h +++ b/include/deal.II/grid/tria_iterator.h @@ -237,7 +237,8 @@ public: using AccessorType = Accessor; /** - * Empty constructor. Such an object is not usable! + * Default constructor. This constructor creates an iterator pointing + * to an invalid object. The iterator is consequently not usable. */ TriaRawIterator(); @@ -573,7 +574,8 @@ class TriaIterator : public TriaRawIterator { public: /** - * Empty constructor. Such an object is not usable! + * Default constructor. This constructor creates an iterator pointing + * to an invalid object. The iterator is consequently not usable. */ TriaIterator(); @@ -583,21 +585,26 @@ public: TriaIterator(const TriaIterator &); /** - * Cross copy constructor from iterators pointing also to non-active - * objects. + * Conversion constructor from iterators potentially pointing to non-active + * objects (i.e., for objects for which we can't tell that the object is + * used just by looking at its type). * - * If the object pointed to is not past-the-end and is not used, the debug - * version raises an error! + * @pre This constructor will throw an exception if not one of the + * following two conditions are satisfied: (i) the object + * represented by the argument is past-the-end; or (ii) the + * argument represents a used object. */ TriaIterator(const TriaRawIterator &); /** - * Proper constructor, initialized with the triangulation, the level and + * Constructor, initialized with the triangulation, the level and * index of the object pointed to. The last parameter is of a type declared * by the accessor class. * - * If the object pointed to is not past-the-end and is not used, the debug - * version raises an error! + * @pre This constructor will throw an exception if not one of the + * following two conditions are satisfied: (i) the object + * represented by the argument is past-the-end; or (ii) the + * argument represents a used object. */ TriaIterator( const Triangulation *parent, @@ -716,7 +723,7 @@ public: /*@}*/ /** - * Declare some alias which are standard for iterators and are used + * Declare some aliases which are standard for iterators and are used * by algorithms to enquire about the specifics of the iterators they * work on. */ @@ -748,7 +755,8 @@ class TriaActiveIterator : public TriaIterator { public: /** - * Empty constructor. Such an object is not usable! + * Default constructor. This constructor creates an iterator pointing + * to an invalid object. The iterator is consequently not usable. */ TriaActiveIterator(); @@ -758,30 +766,38 @@ public: TriaActiveIterator(const TriaActiveIterator &); /** - * Cross copy constructor from iterators pointing also to non-active - * objects. + * Conversion constructor creating an active iterator from an iterators + * pointing to a potentially non-active object (or at least from which + * it is not apparent from the type alone that it is active). * - * If the object pointed to is not past-the-end and is not active, the debug - * version raises an error! + * @pre This constructor will throw an exception if not one of the + * following two conditions are satisfied: (i) the object + * represented by the argument is past-the-end; or (ii) the + * argument represents an active object. */ TriaActiveIterator(const TriaRawIterator &); /** - * Cross copy constructor from iterators pointing also to non-active - * objects. + * Conversion constructor creating an active iterator from an iterators + * pointing to a potentially non-active object (or at least from which + * it is not apparent from the type alone that it is active). * - * If the object pointed to is not past-the-end and is not active, the debug - * version raises an error! + * @pre This constructor will throw an exception if not one of the + * following two conditions are satisfied: (i) the object + * represented by the argument is past-the-end; or (ii) the + * argument represents an active object. */ TriaActiveIterator(const TriaIterator &); /** - * Proper constructor, initialized with the triangulation, the level and + * Constructor, initialized with the triangulation, the level and * index of the object pointed to. The last parameter is of a type declared - * by the accessor class. + * by the accessor class used by the current iterator. * - * If the object pointed to is not past-the-end and is not active, the debug - * version raises an error! + * @pre This constructor will throw an exception if not one of the + * following two conditions are satisfied: (i) the object + * represented by the argument is past-the-end; or (ii) the + * argument represents an active object. */ TriaActiveIterator( const Triangulation *parent, @@ -818,6 +834,11 @@ public: * for raw iterators. Since usual iterators are also raw iterators, this * constructor works also for parameters of type * TriaIterator. + * + * @pre This constructor will throw an exception if not one of the + * following two conditions are satisfied: (i) the object + * represented by the argument is past-the-end; or (ii) the + * argument represents an active object. */ template TriaActiveIterator(const TriaRawIterator &i); -- 2.39.5