Changes in documentation

1 files changed, 122 insertions, 15 deletions

diff --git a/utils/HashTable.cc b/utils/HashTable.cc
index 03bfd9a..98de9ce 100644
--- a/utils/HashTable.cc
+++ b/utils/HashTable.cc
@@ -31,9 +31,9 @@ A hash table is made of a set of hash entries (of class \typ{CcuHashCell}),
 which can be modified during
 the life of the table. An entry has two main fields: a hash key, and a user defined
 information attached to that key. We will not give details about the structure of
-a hash table, as they can be found in any book about algorithms. Figure~\ref{fig:hash} is only
+a hash table, as they can be found in any book about algorithms. Figure~\ref{FIGURES/hash} is only
 here as a reminder.
-\fig{hash}{Internals of a hash table}
+\fig{FIGURES/hash}{Internals of a hash table}
 The current implementation uses lists to store the synonyms so that entries can
 be deleted efficiently.
 
@@ -43,13 +43,24 @@ The class \typ{CcuHashTable} makes no assumption about the type of the keys, whi
 The user can define several functions used when managing a hash table: the hash function, which 
 is determinant for the performances of the hash table, and the functions to copy, compare, and
 destroy keys. Basic functions are provided by default.
+The following definitions are used by member functions of the class \typ{CcuHashTable},
+and by them only:
+\index{HASH_F}\index{HCP_F}\index{HCMP_F}\index{HENUM_F}\index{HDEL_F}
+\begin{ccode}
+        typedef int     (*HASH_F) (HashItem*, int);
+        typedef pointer (*HCP_F) (HashItem*);
+        typedef int     (*HCMP_F) (HashItem*, HashItem*);
+        typedef int     (*HENUM_F) (HashCell*, HashItem*);
+        typedef void    (*HDEL_F) (HashCell*);
+\end{ccode}
+
 ?*/
 
 
 
 CcuAllocator* CcuHashCell::HashCellMem = 0;
 
-/*?nodoc?*/ 
+/*?hidden?*/ 
 void
 CcuHashCell :: ClassInit ()
 {
@@ -288,11 +299,6 @@ CcuHashTable :: Get (const void* key)
 }
 
 #if 0
-/*?
-Get a reference to the data stored in the table for the key \var{key}. That
-reference can be used for reading as for writing. If the key was not present
-in the table, a new entry is created.
-?*/
 CcuHashItem*&
 CcuHashTable :: operator [] (const void* key)
 {
@@ -305,6 +311,12 @@ CcuHashTable :: operator [] (const void* key)
 	return h->Info;
 }
 #else
+/*?
+Get a reference to the data stored in the table for the key \var{key}. That
+reference can be used for reading as for writing. If the key was not present
+in the table, a new entry is created when writing, and a default (invalid) entry
+is returned when reading.
+?*/
 CcuHashCellRef
 CcuHashTable :: operator [] (const void* key) const
 {
@@ -420,7 +432,7 @@ CcuHashTable :: HashStats (int fd)
 
 /*?
 Print some statistics about this hash table on file descriptor \var{fd}
-(default is standard error).
+(default is stderr).
 ?*/
 void
 CcuHashTable :: CollStats (int fd)
@@ -492,7 +504,7 @@ function \fun{NewString} (see page~\pageref{newstring}). If users do not provide
 a default one is used.
 
 All the functions of class \typ{CcuHashTable} are available in class \typ{CcuDictionnary}.
-The iterator \typ{Hashiter} can be used on \typ{CcuDictionnary} as well.
+\typ{CcuHashCellIter}s and \typ{CcuHashIter}s can be used on \typ{CcuDictionnary}s as well.
 ?*/
 
 
@@ -561,20 +573,22 @@ CcuDictionnary :: KeyCopy (int flag)
 	}
 }
 
-/*?class Hashiter
-The class \typ{Hashiter} makes it possible to iterate through the entries of an hash table.
+/*?class CcuHashCellIter
+The class \typ{CcuHashCellIter} makes it possible to iterate through the entries of an hash table.
+The order of iteration is not specified. These iterators yield pointers to cells, so that keys
+and entries are both accessible. To see only the entries, refer to the class \typ{CcuHashIter}.
 ?*/
 
 #ifdef DOC
 /*?
 Constructor for \typ{CcuHashCellIter}s. Initialize an iterator on the hash table \var{t}.
 ?*/
-CcuHashCellIterOf :: CcuHashCellIter (const CcuHashTable& t)
+CcuHashCellIter :: CcuHashCellIter (const CcuHashTable& t)
 {
 }
 
 /*?
-Get the current cell  pointed by an interator.
+Get the current cell  pointed by an iterator.
 ?*/
 CcuHashCell*
 CcuHashCellIter :: operator * () const
@@ -614,6 +628,10 @@ CcuHashCellIter :: operator ++ (int)
 }
 #endif
 
+/*?
+Get the status of an iterator. The status may be one of \var{Normal, StartOfTable}, or
+\var{EndOfTable}
+?*/
 #ifndef CPLUS_BUG13
 CcuHashCellIter::
 #endif
@@ -628,8 +646,97 @@ CcuHashCellIter :: Status () const
 }
 
 #ifdef DOC
+/*?
+Check whether the status of an iterator is \var{Normal}.
+?*/
 CcuHashCellIter :: operator int () const
 {
 }
-#endif
 
+/*?class CcuHashIter
+\typ{CcuHashIter}s are iterators that yield entries and not cells. They only differ
+from \typ{CcuHashCellIter}s by their operator \fun{*}.
+?*/
+
+/*?
+Get the current entry  pointed by an iterator.
+?*/
+CcuHashItem*
+CcuHashIter :: operator * () const
+{
+}
+
+/*?class CcuHashTableOf
+The generic classes \typ{CcuHashTableOf, CcuHashCellOf, CcuHashCellIterOf}
+and \typ{CcuHashIterOf} are derived classes of \typ{CcuHashTable, CcuHashCell, CcuHashCellIter}
+and \typ{CcuHashIter} that provide hash tables whose entries are
+pointers to class objects.
+When parameterized by the class \typ{ITEM}, the following functions are redefined:
+?*/
+
+/*?nextdoc?*/
+CcuHashCellOf<ITEM>*
+CcuHashTableOf :: Add (const void* key, int* found)
+{
+}
+
+/*?nextdoc?*/
+CcuHashCellOf<ITEM>*
+CcuHashTableOf :: Get (const void* key)
+{
+}
+
+/*?nextdoc?*/
+ITEM*
+CcuHashTableOf :: Remove (const void* key, int* found)
+{
+}
+
+/*?
+These functions are equivalent to their homonyms in the class \typ{CcuHashTable},
+except that they are customized in order to manipulate pointers to \typ{ITEM}
+instead of \typ{void*}.
+?*/
+CcuHashCellRefOf<ITEM>
+CcuHashTableOf :: operator [] (const void* key) const
+{
+}
+
+/*?nextdoc?*/
+void
+CcuHashCellOf :: SetInfo (ITEM* p)
+{
+}
+
+/*?
+These functions are equivalent to their homonyms in the class \typ{CcuHashCell},
+except that they are customized in order to manipulate pointers to \typ{ITEM}
+instead of \typ{void*}.
+?*/
+ITEM*
+CcuHashCellOf :: GetInfo () const
+{
+}
+
+/*?nextdoc?*/
+CcuHashIterOf :: CcuHashIterOf (const CcuHashTableOf<ITEM>& t)
+{
+}
+
+/*?nextdoc?*/
+CcuHashIterOf<ITEM>&
+CcuHashIterOf :: operator ++ ()
+{
+}
+
+/*?
+These functions are equivalent to their homonyms in the class \typ{CcuHashIter},
+except that they are customized in order to manipulate pointers to \typ{ITEM}
+instead of \typ{void*}.
+?*/
+ITEM*
+CcuHashIterOf :: operator * () const
+{
+}
+
+#endif