From d913adc42e2234e8597ff69af3bcf7bffcff79a7 Mon Sep 17 00:00:00 2001
From: Stefan Huehner <shuehner@gna.org>
Date: Tue, 19 Sep 2006 19:58:06 +0000
Subject: [PATCH] Add doxygen comments the the hashtable header

git-svn-id: svn+ssh://svn.gna.org/svn/warzone/trunk@732 4a71c877-e1ca-e34f-864e-861f7616d084
---
 lib/gamelib/hashtabl.h | 110 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 109 insertions(+), 1 deletion(-)

diff --git a/lib/gamelib/hashtabl.h b/lib/gamelib/hashtabl.h
index eb621dad6..0354296d8 100644
--- a/lib/gamelib/hashtabl.h
+++ b/lib/gamelib/hashtabl.h
@@ -1,5 +1,13 @@
 /***************************************************************************/
 
+/*! \file hashtabl.h
+ * \brief A generic implementation of a hashtable
+ *
+ * The hashtable can store elements indexed by two keys.
+ * Additionally traversing the stored elements similar to an
+ * singliy-linked list is possible.
+ */
+
 #ifndef _HASHTABL_H_
 #define _HASHTABL_H_
 
@@ -18,7 +26,22 @@
 /* macros
  */
 
+/**
+ * Hashing function
+ *
+ * \param	iKey1		first key
+ * \param	iKey2		second key
+ * \return calculated hash-value for the keys
+ * \see hashTable_SetHashFunction
+ */
 typedef UDWORD	(* HASHFUNC)		( int iKey1, int iKey2 );
+
+/**
+ * Free Element function
+ *
+ * \param	psElement	the element to be freed
+ * \see hashTable_SetFreeElementFunction
+ */
 typedef void	(* HASHFREEFUNC)	( void *psElement );
 
 /***************************************************************************/
@@ -54,24 +77,109 @@ HASHTABLE;
 /* functions
  */
 
+/**
+ * Function to create a new hashtable
+ *
+ * \param	ppsTable	out-parameter which holds the created hashtable
+ * \param	udwTableSize	size of the hashtable in elements
+ * \param	udwInitElements	initial number of elements of the heap used to store the nodes
+ * \param	udwExtElements	number of elements when extending the heap
+ * \param	udwElementSize	size of elements to be stored in the hashtable
+ */
 BOOL	hashTable_Create( HASHTABLE **ppsTable, UDWORD udwTableSize,
 							UDWORD udwInitElements, UDWORD udwExtElements,
 							UDWORD udwElementSize );
-void	hashTable_Destroy( HASHTABLE *psTable );
+
+/**
+ * Function to destroy a hashtable
+ *
+ * \param	psTable		the hashtable to be destroyed
+ */
+void    hashTable_Destroy( HASHTABLE *psTable );
+
+/**
+ * Returns all nodes from hash table to free node list
+ *
+ * \param	psTable		the hashtable to be cleared
+ */
 void	hashTable_Clear( HASHTABLE *psTable );
 
+/**
+ * Gets free node from heap and returns element pointer
+ * 
+ * \param	psTable		the hashtable
+ * \return	pointer to the element
+ */
 void *	hashTable_GetElement( HASHTABLE *psTable );
+
+/**
+ * Function to insert an element into the hashtable
+ *
+ * \param	psTable		the hashtable
+ * \param	psElement	the element to be inserted
+ * \param	iKey1		first key
+ * \param	iKey2		second key
+ */
 void	hashTable_InsertElement( HASHTABLE *psTable, void *psElement,
 										int iKey1, int iKey2 );
+
+/**
+ * Function to remove an element from the hashtable
+ *
+ * \param	psTable		the hashtable
+ * \param	psElement	element to be removed
+ * \param	iKey1		first key
+ * \param	iKey2		second key
+ * \return	true, if the element was contained in the hashtable
+ */
 BOOL	hashTable_RemoveElement( HASHTABLE *psTable, void *psElement,
 										int iKey1, int iKey2 );
+
+/**
+ * Calculates hash index from keys and returns element in hash table
+ *
+ * \param	psTable		the hashtable
+ * \param	iKey1		first key
+ * \param	iKey2		second key
+ * \return	the element
+ */
 void *	hashTable_FindElement( HASHTABLE *psTable,
 										int iKey1, int iKey2 );
 
+/**
+ * Gets the first allocated element from the hashtable
+ *
+ * \param	psTable		the hashtable
+ * \see		hashTable_GetNext
+ * \return	the first element
+ */
 void *	hashTable_GetFirst( HASHTABLE *psTable );
+
+/**
+ * Gets the next allocated element from the hashtable
+ *
+ * \param	psTable		the hashtable
+ * \see		hashTable_GetFirst
+ * \return	next element
+ */
 void *	hashTable_GetNext(  HASHTABLE *psTable );
 
+/**
+ * Function to the the hashing function to be used
+ *
+ * \param	psTable		the hashtable
+ * \param	pHashFunc	the hashing function
+ * \see HASHFUNC
+ */
 void	hashTable_SetHashFunction( HASHTABLE *psTable, HASHFUNC pHashFunc );
+
+/**
+ * Sets the function to be called when freeing an element.
+ *
+ * \param	psTable		the hashtable
+ * \param	pFreeFunc	the free function
+ * \see HASHFREEFUNC
+ */
 void	hashTable_SetFreeElementFunction( HASHTABLE *psTable,
 											HASHFREEFUNC pFreeFunc );