Improved the documentation regarding garbage collection and iterators.

closes #1010

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

Doc/Concepts/MeshKernel.hh

@@ -181,6 +181,7 @@ public:
       \note All handles (and indices) to any entity (face, vertex,
             edge, halfedge) created before garbage collection
             will be out of sync with the mesh, do not use them anymore!
+            See also \ref deletedElements.
       \note Needs the Attributes::Status attribute
       \note This function may not be implemented for all kernels.
   */

Doc/mesh.docu

@@ -755,6 +755,17 @@ Additionally to the standard operations, each linear iterator
 provides a method \c handle(), which returns the handle of the
 item referred to by the iterator.
 
+\subsection deletedElements Deleted Elements
+If no elements of a mesh are marked as deleted, the indices provided by \c idx()
+are consecutive numbers from 0 to <I>number of elements</I>-1 (in the case of vertices this would be
+from 0 to n_vertices()-1).
+
+However, note that this is <B>not</B> the case when elements are marked
+as deleted and OpenMesh::ArrayKernel::garbage_collection() has not yet been called.
+
+After garbage_collection() has been called the elements are reorganized and their handles and
+iterators are guaranteed to be consecutive numbers again.
+
 \note
 <ul>
 <li>If you delete elements on the mesh, they will still be

src/OpenMesh/Core/Mesh/ArrayKernel.hh

@@ -269,10 +269,12 @@ public:
    * \note Garbage collection invalidates all handles. If you need to keep track of
    *       a set of handles, you can pass them to the second garbage collection
    *       function, which will update a vector of handles.
+   *       See also \ref deletedElements.
    *
    * @param _v Remove deleted vertices?
    * @param _e Remove deleted edges?
    * @param _f Remove deleted faces?
+   *
    */
   void garbage_collection(bool _v=true, bool _e=true, bool _f=true);
 
@@ -284,8 +286,7 @@ public:
    * \note Garbage collection invalidates all handles. If you need to keep track of
    *       a set of handles, you can pass them to this function. The handles that the
    *       given pointers point to are updated in place.
-   *
-   *
+   *       See also \ref deletedElements.
    *
    * @param vh_to_update Pointers to vertex handles that should get updated
    * @param hh_to_update Pointers to halfedge handles that should get updated