From b8ef9d77a97a00b4005adc28412baf13b6dc32f8 Mon Sep 17 00:00:00 2001
From: ganovelli <fabio.ganovelli@isti.cnr.it>
Date: Thu, 7 Jul 2005 13:33:52 +0000
Subject: [PATCH] some comment

---
 vcg/container/container_allocation_table.h | 19 ++++++++++++----
 vcg/container/traced_vector.h              | 26 +++++++++++++++++++++-
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/vcg/container/container_allocation_table.h b/vcg/container/container_allocation_table.h
index 567cf13a..79f8a2dd 100644
--- a/vcg/container/container_allocation_table.h
+++ b/vcg/container/container_allocation_table.h
@@ -24,6 +24,9 @@
   History
 
 $Log: not supported by cvs2svn $
+Revision 1.5  2005/07/06 15:28:10  ganovelli
+aggiornamento di alcuni path
+
 Revision 1.4  2004/04/05 18:20:50  ganovelli
 Aggiunto typename
 Eliminata bug di ricorsione nell'istanzazione dei template
@@ -43,9 +46,17 @@ First Working Release (with this comment)
 #include <assert.h>
 #include <vcg/container/entries_allocation_table.h>
 
-namespace vcg {
 
-// CATBase: abstract base class for all the allocation tables
+namespace vcg {
+	/*@{*/
+/*!
+ * CATBase is the abstract class for all the allocation tables. THese table keep track of
+ * where the traced vector (see traced_ector.h) are kepth in memory.
+ * The goal is to know (given a pointer to a memory location), which is the vector the pointed 
+ * element is in
+ * 
+ */
+
 template <typename STL_CONT>
 class CATBase{
 public:
@@ -63,8 +74,8 @@ static int & Id(){
 			}	
 };
 
-// CATEntry: first derivation templated on the type of entry
-// It implements all the methods to trace and access TVector element
+/// CATEntry: first derivation templated on the type of entry
+/// It implements all the methods to trace and access TVector element
 template <typename STL_CONT, class ENTRY_TYPE>
 class CATEntry: public CATBase<STL_CONT>{
 public:
diff --git a/vcg/container/traced_vector.h b/vcg/container/traced_vector.h
index 21b7bd14..a814bfd6 100644
--- a/vcg/container/traced_vector.h
+++ b/vcg/container/traced_vector.h
@@ -24,6 +24,9 @@
   History
 
 $Log: not supported by cvs2svn $
+Revision 1.4  2004/04/05 18:20:08  ganovelli
+Aggiunto typename
+
 Revision 1.3  2004/03/31 22:36:44  ganovelli
 First Working Release (with this comment)
 
@@ -39,6 +42,14 @@ First Working Release (with this comment)
 #include <assert.h>
 
 namespace vcg {
+	/*@{*/
+/*!
+ * This class represent a Traced Vector. A TVector is derived by a std::vector.
+ * The characteristic of a TVector is that you can add (at run time) new attributes
+ * to the container::value_type elements contained in the vector. (see the example..)
+ * The position in memory of a traced vector is kept by the Container Allocation Table,
+ * which is a (unique) list of TVector positions.
+ */
 
 template <class VALUE_TYPE>
 class TVector: public std::vector<VALUE_TYPE>{
@@ -57,6 +68,7 @@ public:
 	void resize(const unsigned int & size);
 	void reserve(const unsigned int & size);
 
+	/// this function enable the use of an optional attribute (see...)
 	template <class ATTR_TYPE>
 		void EnableAttribute(){
 			CAT<ThisType,ATTR_TYPE> * cat = new CAT<ThisType,ATTR_TYPE>();
@@ -64,6 +76,8 @@ public:
 			attributes.push_back(cat);
 			}
 
+	/// this function disable the use of an optional attribute (see...)
+  /// Note: once an attribute is disabled, its data is lost (the memory freed)
 	template <class ATTR_TYPE>
 		void DisableAttribute(){
 				std::list < CATBase<ThisType> * >::iterator ia; 
@@ -77,6 +91,13 @@ public:
 						}
 				}
 
+	/// this function create a new attribute of type ATTR_TYPE and return an handle to
+  /// access the value of the attribute. Ex:
+  /// TVector<float> tv;
+  /// TempData<TVect,int> handle =  tv.NewTempData<int>();
+  /// // now handle[&tv[123]] is the value of integer attribute associate with the position 123 on the vector
+  /// // NOTE: it works also if you do some push_back, resize, pop_back, reserve that cause the relocation
+  /// // of the TVector
 	template <class ATTR_TYPE>
 		TempData<ThisType,ATTR_TYPE> NewTempData(){
 			typedef typename CATEntry<ThisType,EntryCATMulti<ThisType> >::EntryType EntryTypeMulti;
@@ -89,7 +110,8 @@ public:
 
 			return TempData<ThisType,ATTR_TYPE>((Wrap<ATTR_TYPE>*) entry.Data().back());
 			}
-			
+
+	/// reciprocal of NewTempData
 	template <class ATTR_TYPE>
 		void DeleteTempData(TempData<ThisType,ATTR_TYPE> & td){
 			typedef typename CATEntry<ThisType,EntryCATMulti<ThisType> >::EntryType EntryTypeMulti;
@@ -107,6 +129,8 @@ private:
 	void Update();
 };
 
+	/*@}*/
+
 template <class VALUE_TYPE>
 void TVector<VALUE_TYPE>::push_back(const VALUE_TYPE & v){
 	std::vector<VALUE_TYPE>::push_back(v);