From f4969d5d6774c3d5b86e679e8e0d1b3c6822334d Mon Sep 17 00:00:00 2001
From: Bill Currie <bill@taniwha.org>
Date: Mon, 11 Jun 2001 19:37:25 +0000
Subject: [PATCH] add some docs for the hash table api and move the include of
 stdlib.h to hash.c (no longer needed in hash.h).

---
 include/QF/hash.h | 54 +++++++++++++++++++++++++++++++++++++++++++++--
 libs/util/hash.c  |  2 ++
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/include/QF/hash.h b/include/QF/hash.h
index da071a3f0..17bca476d 100644
--- a/include/QF/hash.h
+++ b/include/QF/hash.h
@@ -30,16 +30,66 @@
 #ifndef __hash_h
 #define __hash_h
 
-#include <stdlib.h> // should be sys/types.h, but bc is stupid
-
 typedef struct hashtab_s hashtab_t;
 
+/*
+	create a new hash table:
+		tsize:	table size. larger values will give better distribution, but
+				use more memory.
+		gk:		a function that returns a string to be used as the key for
+				inserting or finding the element. First parameter is a pointer
+				to the element from which to extract the key, the second is
+				the user data pointer.
+		f:		a function to free the element. Only ever called from
+				Hash_FlushTable and Hash_DelTable. The first parameter is the
+				element to be freed and the second is the user data pointer.
+		ud:		user data pointer. set to whatever you want, it will be passed
+				to the get key and free functions as the second parameter.
+	returns a pointer to the hash table (to be passed to the other functions)
+	or 0 on error.
+
+	multiple inserions of the same key are fine; later insertions override
+	previous ones until the later one is removed (Hash_Del).
+*/
 hashtab_t *Hash_NewTable (int tsize, const char *(*gk)(void*,void*),
 						  void (*f)(void*,void*), void *ud);
+
+/*
+	delete a hash table:
+		tab:	the table to be deleted
+*/
 void Hash_DelTable (hashtab_t *tab);
+
+/*
+	clean out all the entries from a hash table, starting over again:
+		tab:	the table to be cleared
+*/
 void Hash_FlushTable (hashtab_t *tab);
+
+/*
+	add an entry to a hash table:
+		tab:	the table to be added to
+		ele:	the element to add to the table
+	returns 0 for success, -1 for error.
+*/
 int Hash_Add (hashtab_t *tab, void *ele);
+
+/*
+	find an element within a hash table:
+		tab:	the table to search
+		key:	the key string identifying the element being searched for
+	returns a pointer to the element if found, otherwise 0.
+*/
 void *Hash_Find (hashtab_t *tab, const char *key);
+
+/*
+	delete an element from a hash table:
+		tab:	the table to remove the element from
+		key:	the key string identifying the element to be deleted
+	returns 0 on success, -1 if the element could not be found.
+	Does /NOT/ call the free element function. That is the caller's
+	responsibility.
+*/
 int Hash_Del (hashtab_t *tab, const char *key);
 
 #endif // __hash_h
diff --git a/libs/util/hash.c b/libs/util/hash.c
index a5535c806..502961b68 100644
--- a/libs/util/hash.c
+++ b/libs/util/hash.c
@@ -37,6 +37,8 @@
 # include <strings.h>
 #endif
 
+#include <stdlib.h>		// should be sys/types.h, but bc is stupid
+
 #include "QF/hash.h"
 
 #include "compat.h"