updated the documentation for the improved iterators and circulators

git-svn-id: http://www.openmesh.org/svnrepo/OpenMesh/trunk@915 fdac6126-5c0c-442c-9429-916003d36597

Doc/Tutorial/02-iterators/smooth.cc

@@ -49,9 +49,9 @@ int main(int argc, char **argv)
     {
       cog[0] = cog[1] = cog[2] = valence = 0.0;
       
-      for (vv_it=mesh.vv_iter( v_it ); vv_it; ++vv_it)
+      for (vv_it=mesh.vv_iter( *v_it ); vv_it.is_valid(); ++vv_it)
       {
-        cog += mesh.point( vv_it );
+        cog += mesh.point( *vv_it );
         ++valence;
       }
 
@@ -60,8 +60,8 @@ int main(int argc, char **argv)
     
     for (v_it=mesh.vertices_begin(), cog_it=cogs.begin(); 
          v_it!=v_end; ++v_it, ++cog_it)
-      if ( !mesh.is_boundary( v_it ) )
+      if ( !mesh.is_boundary( *v_it ) )
-        mesh.set_point( v_it, *cog_it );
+        mesh.set_point( *v_it, *cog_it );
   }
 
 

Doc/mesh.docu

@@ -744,16 +744,16 @@ The corresponding \c const counterparts are
 \arg \c ConstFaceIter.
 
 
-The linear iterators are (almost) conformant to STL iterators. For a
+The linear iterators are conformant to STL iterators. For a
 description of their interface see OpenMesh::Concepts::IteratorT.
 
-For efficiency reasons the \c operation++(int) (post-increment)
+When using iterators, use the pre-increment operation (++it) for efficiency
-and \c operation--(int) (post-decrement) are not implemented.
+reasons. 
-Hence, when using iterators, use the pre-increment operation
+
-(++it).
+\deprecated
-Additionally to the standard operations, each linear iterator
+While it is possible to use \c handle() to get the handle of the item referred
-provides a method \c handle(), which returns the handle of the
+to by the iterator, this function is deprecated. Simply dereference the iterator
-item referred to by the iterator.
+instead.
 
 \subsection deletedElements Deleted Elements
 If no elements of a mesh are marked as deleted, the indices provided by \c idx()
@@ -842,9 +842,10 @@ All circulators provide the operations listed in
 CirculatorT<Mesh>, which are basically the same as the
 iterator funtions.
 
-Furthermore, circulators provide \c operator \c bool(), which returns
+\deprecated
-true, as long as the circulator hasn't reached the end of the
+While it is possible to use \c operator \c bool(), which returns true, as long
-sequence.
+as the circulator hasn't reached the end of the sequence, this function is
+deprecated. Use the function \c is_valid() instead.
 
 %OpenMesh provides the following functions (defined in OpenMesh::PolyConnectivity)
 to get circulators around a specified center item:
@@ -889,7 +890,7 @@ MyMesh mesh;
 
 MyMesh::FaceHalfedgeIter fh_it = mesh.fh_iter(faceHandle);
 
-for(; fh_it; ++fh_it) {
+for(; fh_it.is_valid(); ++fh_it) {
     std::cout << "Halfedge has handle " << *fh_it << std::endl;
 }
 

src/OpenMesh/Core/Mesh/CirculatorsT.hh

@@ -314,22 +314,41 @@ class GenericCirculatorT : protected GenericCirculatorBaseT<Mesh> {
         }
 
         //DEPRECATED("current_halfedge_handle() is an implementation detail and should not be accessed from outside the iterator class.")
+        /**
+         * \deprecated
+         * current_halfedge_handle() is an implementation detail and should not
+         * be accessed from outside the iterator class.
+         */
         const HalfedgeHandle &current_halfedge_handle() const {
             return this->heh_;
         }
 
         DEPRECATED("Do not use this error prone implicit cast. Compare to end-iterator or use is_valid(), instead.")
+        /**
+         * \deprecated
+         * Do not use this error prone implicit cast. Compare to the
+         * end-iterator or use is_valid() instead.
+         */
         operator bool() const {
             return is_valid();
         }
 
-        /// Return the handle of the current target.
+        /**
+         * \brief Return the handle of the current target.
+         * \deprecated
+         * This function clutters your code. Use dereferencing operators -> and * instead.
+         */
         DEPRECATED("This function clutters your code. Use dereferencing operators -> and * instead.")
         value_type handle() const {
           return **this;
         }
 
-        /// Cast to the handle of the current target.
+        /**
+         * \brief Cast to the handle of the current target.
+         * \deprecated
+         * Implicit casts of iterators are unsafe. Use dereferencing operators
+         * -> and * instead.
+         */
         DEPRECATED("Implicit casts of iterators are unsafe. Use dereferencing operators -> and * instead.")
         operator value_type() const {
           return **this;

src/OpenMesh/Core/Mesh/IteratorsT.hh

@@ -117,13 +117,22 @@ class GenericIteratorT {
             return &hnd_;
         }
 
-        /// Get the handle of the item the iterator refers to.
+        /**
+         * \brief Get the handle of the item the iterator refers to.
+         * \deprecated 
+         * This function clutters your code. Use dereferencing operators -> and * instead.
+         */
         DEPRECATED("This function clutters your code. Use dereferencing operators -> and * instead.")
         value_handle handle() const {
             return hnd_;
         }
 
-        /// Cast to the handle of the item the iterator refers to.
+        /**
+         * \brief Cast to the handle of the item the iterator refers to.
+         * \deprecated
+         * Implicit casts of iterators are unsafe. Use dereferencing operators
+         * -> and * instead.
+         */
         DEPRECATED("Implicit casts of iterators are unsafe. Use dereferencing operators -> and * instead.")
         operator value_handle() const {
             return hnd_;