Improving Documentation: removed a ton of doxygen warnings. Cleared a bit the groups structure, added a few comments to allocator

apps/sample/trimesh_allocate/trimesh_allocate.cpp

@@ -23,7 +23,7 @@
 /*! \file trimesh_allocate.cpp
 \ingroup code_sample
 
-\brief the minimal example of using the attributes
+\brief the minimal example about creating and deleting elements
 
 Attributes are a simple mechanism to associate user-defined 'attributes' to the simplicies and to the mesh.
 \ref attributes for more Details
@@ -95,6 +95,10 @@ int main()
        }
   }
 
+  // To remove the elements marked as deleted use
+  vcg::tri::Allocator<MyMesh>::CompactFaceVector(m);
+  vcg::tri::Allocator<MyMesh>::CompactVertexVector(m);
+
   // finally lets copy this mesh onto another one.
   MyMesh m2;
   vcg::tri::Append<MyMesh,MyMesh>::MeshCopy(m2,m);

docs/Doxygen/allocation.dxy

@@ -42,10 +42,9 @@ Therefore when you scan the containers of vertices and faces you could encounter
 \until  }
 \until }
 In some situations, particularly when you have to loop many many times over the element of the mesh without deleting/creating anything, it can be practical and convenient to get rid of deleted elements by explicitly calling the two garbage collecting functions:
-\code
+\dontinclude trimesh_allocate.cpp
-vcg::tri::Allocator<MyMesh>::CompactVertexVector(m);
+\skip CompactFaceVector
-vcg::tri::Allocator<MyMesh>::CompactFaceVector(m);
+\until  CompactVertexVector
-\endcode
 After calling these function it is safe to not check the IsD() state of every element and always holds that:
 \code
 m.vert.size() == m.VN()

vcg/complex/allocate.h

@@ -46,7 +46,9 @@ public:
 };
 
 	namespace tri {
-		/** \addtogroup trimesh */
+/** \addtogroup trimesh
+@{
+*/
 		
 		template<class MeshType>
 		size_t Index(MeshType &m, const typename MeshType::VertexType &v) {return &v-&*m.vert.begin();}
@@ -80,7 +82,6 @@ public:
 					((typename MeshType::PointerToAttribute)(*ai)).Resize(sz);
 		}
 
-		/*@{*/
 		/*!
 		\brief  Class to safely add and delete elements in a mesh.
 
@@ -336,12 +337,14 @@ public:
 
 
       /* ++++++++++ hedges +++++++++++++ */
-			/** Function to add n edges to the mesh. The second parameter hold a vector of
+            /** Function to add n halfedges to the mesh. The second parameter hold a vector of
 			pointers to pointer to elements of the mesh that should be updated after a
 			possible vector realloc.
-			@param n number of edges to be added
+			\sa PointerUpdater
-			@param local_var vector of pointers to pointers to edges to be updated.
+			\param m the mesh to be modified
-			return an iterator to the first element added
+			\param n the number of elements to be added
+			\param pu  a PointerUpdater initialized so that it can be used to update pointers to edges that could have become invalid after this adding.
+			\retval the iterator to the first element added.
 			*/
 			static HEdgeIterator AddHEdges(MeshType &m,int n, PointerUpdater<HEdgePointer> &pu)
 			{
@@ -659,12 +662,13 @@ public:
 		}
 
 
-		/* 
+		/*!
-		Function to compact all the vertices that have been deleted and put them to the end of the vector. 
+		\brief Compact vector of vertices removing deleted elements.
-		after this pass the isD test in the scanning of vertex vector, is no more strongly necessary.
+		Deleted elements are put to the end of the vector and the vector is resized. Order between elements is preserved but not their position (hence the PointerUpdater)
-		It should not be called when TemporaryData is active;
+		After calling this function the \c IsD() test in the scanning a vector, is no more necessary.
-		*/
 
+		\warning It should not be called when TemporaryData is active (but works correctly if attributes are present)
+		*/
 		static void CompactVertexVector( MeshType &m,   PointerUpdater<VertexPointer> &pu   )
 		{
 			// If already compacted fast return please!
@@ -690,21 +694,20 @@ public:
 			 
 		}
 
-		/* 
+		/*! \brief Wrapper without the PointerUpdater. */
-		Function to compact all the verices that have been deleted and put them to the end of the vector. 
-		Wrapper if not PointerUpdater is not wanted
-		*/
 		static void CompactVertexVector( MeshType &m  ) {
 			PointerUpdater<VertexPointer>  pu;
 			CompactVertexVector(m,pu);
 		}
 
-    /*
+	/*!
-    Function to compact all the vertices that have been deleted and put them to the end of the vector.
+	\brief Compact vector of edges removing deleted elements.
-    after this pass the isD test in the scanning of vertex vector, is no more strongly necessary.
-    It should not be called when TemporaryData is active;
-    */
 
+	Deleted elements are put to the end of the vector and the vector is resized. Order between elements is preserved but not their position (hence the PointerUpdater)
+	After calling this function the \c IsD() test in the scanning a vector, is no more necessary.
+
+	\warning It should not be called when TemporaryData is active (but works correctly if attributes are present)
+	*/
 	static void CompactEdgeVector( MeshType &m,   PointerUpdater<EdgePointer> &pu   )
     {
       // If already compacted fast return please!
@@ -789,21 +792,19 @@ public:
           }
     }
 
-    /*
+    /*! \brief Wrapper without the PointerUpdater. */
-    Function to compact all the verices that have been deleted and put them to the end of the vector.
-    Wrapper if not PointerUpdater is not wanted
-    */
     static void CompactEdgeVector( MeshType &m  ) {
       PointerUpdater<EdgePointer>  pu;
       CompactEdgeVector(m,pu);
     }
 
-		/* 
+		/*!
-		Function to compact all the vertices that have been deleted and put them to the end of the vector. 
+		\brief Compact vector of faces removing deleted elements.
-		after this pass the isD test in the scanning of vertex vector, is no more strongly necessary.
-		It should not be called when TemporaryData is active;
-		*/
 
+		Deleted elements are put to the end of the vector and the vector is resized. Order between elements is preserved but not their position (hence the PointerUpdater)
+		After calling this function the \c IsD() test in the scanning a vector, is no more necessary.
+		\warning It should not be called when TemporaryData is active (but works correctly if attributes are present)
+		*/
 		static void CompactFaceVector( MeshType &m, PointerUpdater<FacePointer> &pu )
 		{
 		  // If already compacted fast return please!
@@ -900,10 +901,7 @@ public:
 
 		}
 
-		/* 
+		/*! \brief Wrapper without the PointerUpdater. */
-		Function to compact all the face that have been deleted and put them to the end of the vector. 
-		Wrapper if not PointerUpdater is wanted
-		*/
 		static void CompactFaceVector( MeshType &m  ) {
 			PointerUpdater<FacePointer>  pu;
 			CompactFaceVector(m,pu);

vcg/complex/complex.h

@@ -39,7 +39,6 @@
 namespace vcg {
 namespace tri {
 /** \addtogroup trimesh */
-/*@{*/
 /*@{*/
 
 
@@ -205,9 +204,9 @@ class TriMesh
 
 	/// Container of half edges, usually a vector.
 	HEdgeContainer hedge;	
-	/// Current number of hedges
+	/// Current number of halfedges; this member is for internal use only. You should always use the HN() member
 	int hn;
-	/// Current number of hedges; this member is for internal use only. You should always use the HN() member
+	/// Current number of halfedges;
 	inline int HN() const { return hn; }
 
 	/// Bounding box of the mesh
@@ -298,7 +297,7 @@ private:
 	Color4b c;
 public:
 
-	inline const Color4b & C() const
+	inline Color4b C() const
 	{
 		return c;
 	}
@@ -403,28 +402,42 @@ template <class MeshType> inline  void InitVertexIMark(MeshType & m)
 		if( !(*vi).IsD() && (*vi).IsRW() )
 			(*vi).InitIMark();
 }
-/** Access function to the incremental mark. 
+/** \brief Access function to the incremental mark.
+  You should not use this member directly. In most of the case just use IsMarked() and Mark()
 */
 template <class MeshType> inline int & IMark(MeshType & m){return m.imark;}
 
-/** Check if the vertex incremental mark matches the one of the mesh. 
+/** \brief Check if the vertex incremental mark matches the one of the mesh.
-	@param v Vertex pointer
+	@param m the mesh containing the element
-*/
+	@param v Vertex pointer */
 template <class MeshType> inline bool IsMarked(MeshType & m, typename MeshType::ConstVertexPointer  v )  { return v->IMark() == m.imark; }
-/** Check if the face incremental mark matches the one of the mesh. 
+
-	@param v Face pointer
+/** \brief Check if the face incremental mark matches the one of the mesh.
-*/
+	@param m the mesh containing the element
+	@param f Face pointer */
 template <class MeshType> inline bool IsMarked( MeshType & m,typename MeshType::ConstFacePointer f )  { return f->IMark() == m.imark; }
-/** Set the vertex incremental mark of the vertex to the one of the mesh.
+
-	@param v Vertex pointer
+/** \brief Set the vertex incremental mark of the vertex to the one of the mesh.
-*/
+	@param m the mesh containing the element
+	@param v Vertex pointer */
 template <class MeshType> inline void Mark(MeshType & m, typename MeshType::VertexPointer v )  { v->IMark() = m.imark; }
-/** Set the face incremental mark of the vertex to the one of the mesh.
+
-	@param v Vertex pointer
+/** \brief Set the face incremental mark of the vertex to the one of the mesh.
-*/
+	@param m the mesh containing the element
+	@param f Vertex pointer */
 template <class MeshType> inline void Mark(MeshType & m, typename MeshType::FacePointer f )  { f->IMark() = m.imark; }
-/// Unmark the mesh
+
-template <class MeshType> inline void UnMarkAll(MeshType & m) { ++m.imark; }
+
+/** \brief Unmark, in constant time, all the elements (face and vertices) of a mesh.
+    @param m the mesh containing the element
+
+    In practice this function just increment the internal counter that stores the value for which an element is considered marked;
+    therefore all the mesh elements become immediately un-mmarked.
+    */
+template <class MeshType> inline void UnMarkAll(MeshType & m)
+{
+  ++m.imark;
+}
 
 
 template < class CType0, class CType1 , class CType2, class CType3>