Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add doxygen comments to hash_table.h (refs #58)

  • Loading branch information...
commit 9a5e51de799919a8cd8a92a309d08a88d873c164 1 parent 6aa9c0b
Yasuhito Takamiya yasuhito authored
Showing with 56 additions and 1 deletion.
  1. +1 −1  Doxyfile
  2. +55 −0 src/lib/hash_table.h
2  Doxyfile
View
@@ -557,7 +557,7 @@ WARNINGS = YES
# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
# automatically be disabled.
-WARN_IF_UNDOCUMENTED = YES
+WARN_IF_UNDOCUMENTED = NO
# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some
55 src/lib/hash_table.h
View
@@ -22,6 +22,25 @@
/**
* @file
+ *
+ * @brief Associations between keys and values so that given a key the
+ * value can be found quickly.
+ *
+ * @code
+ * // Create hash table.
+ * table = create_hash( compare_string, hash_string );
+ *
+ * // Insert three key/value pairs.
+ * insert_hash_entry( table, "alpha", &object_a );
+ * insert_hash_entry( table, "bravo", &object_b );
+ * insert_hash_entry( table, "charlie", &object_c );
+ *
+ * // Look up by a key = "alpha".
+ * lookup_hash_entry( table, "alpha" ); // => object_a
+ *
+ * // Delete entire hash table.
+ * delete_hash( table );
+ * @endcode
*/
@@ -32,16 +51,46 @@
#include "doubly_linked_list.h"
+/**
+ * The function is passed a key and should return a unsigned int hash
+ * value.
+ *
+ * The hash values should be evenly distributed over a fairly large
+ * range. The modulus is taken with the hash table size (a prime
+ * number) to find the 'bucket' to place each key into. The function
+ * should also be very fast, since it is called for each key lookup.
+ *
+ * @param key a key.
+ * @return the hash value corresponding to the key.
+ */
typedef unsigned int ( *hash_function )( const void *key );
+
+/**
+ * Specifies the type of a function used to test two values for
+ * equality. The function should return true if both values are equal
+ * and false otherwise.
+ *
+ * @param x a value.
+ * @param y a value to compare with.
+ * @return true if a = b; false otherwise.
+ */
typedef bool ( *compare_function )( const void *x, const void *y );
+/**
+ * The hash_entry struct is an opaque data structure to represent a
+ * key/value pair of hash_table.
+ */
typedef struct {
void *key;
void *value;
} hash_entry;
+/**
+ * The hash_table struct is an opaque data structure to represent a
+ * hash_table. It should only be accessed via the following functions.
+ */
typedef struct {
unsigned int number_of_buckets;
compare_function compare;
@@ -52,6 +101,12 @@ typedef struct {
} hash_table;
+/**
+ * A hash_iterator structure represents an iterator that can be used
+ * to iterate over the elements of a hash_table. hash_iterator
+ * structures are typically allocated on the stack and then
+ * initialized with init_hash_iterator().
+ */
typedef struct {
dlist_element **buckets;
dlist_element *bucket_index;
Please sign in to comment.
Something went wrong with that request. Please try again.