docs: libhashkit

diff --git a/docs/source/libhashkit.rst b/docs/source/libhashkit.rst
index e23c92482733aad9f8f2ae732740aa56743aa764..9bda5cb7acda496cba534dfff19bfc1d01e7dad3 100644 (file)
--- a/docs/source/libhashkit.rst
+++ b/docs/source/libhashkit.rst
@@ -11,7 +11,7 @@ DESCRIPTION
 -----------
 
 `libhashkit` is a small and thread-safe client library that provides a collection
-of useful hashing algorithm.
+of useful hashing algorithms.
 
 `libhashkit` is distributed with `libmemcached`.
 

diff --git a/docs/source/libhashkit/hashkit_create.rst b/docs/source/libhashkit/hashkit_create.rst
index e74550f59c1d1629d52f3992ada85e071537949a..670bdd9cd50d6c85aaa5749e9eea0cb7d3197fba 100644 (file)
--- a/docs/source/libhashkit/hashkit_create.rst
+++ b/docs/source/libhashkit/hashkit_create.rst
@@ -11,17 +11,31 @@ SYNOPSIS
 
 .. function:: hashkit_st *hashkit_create(hashkit_st *hash)
 
+    :param hash: memory address of a `hashkit_st` struct;
+        if a nullptr is passed, the struct will be dynamically allocated by libhashkit
+    :returns: pointer to initialized `hashkit_st` structure
+
 .. function:: hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr)
 
+    :param destination: memory address of a `hashkit_st` struct;
+        if a nullptr is passed, the struct will be dynamically allocated by libhashkit
+    :param ptr: pointer of the `hashkit_st` struct to copy
+    :returns: pointer to a `hashkit_st` structure (`destination`, if not nullptr), initialized from `ptr`
+
 .. function:: void hashkit_free(hashkit_st *hash)
 
+    :param hash: pointer to an initialized `hashkit_st` struct
+
 .. function:: bool hashkit_is_allocated(const hashkit_st *hash)
 
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :returns: bool, whether the `hash` struct was dynamically allocated
+
 DESCRIPTION
 -----------
 
 The `hashkit_create` function initializes a hashkit object for use. If you pass
-a NULL argument for hash, then the memory for the object is allocated. If you
+a nullptr argument for hash, then the memory for the object is allocated. If you
 specify a pre-allocated piece of memory, that is initialized for use.
 
 The `hashkit_clone` function initializes a hashkit object much like
@@ -31,14 +45,14 @@ of the ptr hashkit object.
 The `hashkit_free` frees any resources being consumed by the hashkit objects
 that were initialized with `hashkit_create` or `hashkit_clone`.
 
-The `hashkit_is_allocated` reports where the memory was allocated for a hashkit
+The `hashkit_is_allocated` reports whether the memory was allocated for a hashkit
 object.
 
 RETURN VALUE
 ------------
 
-`hashkit_create` and `hashkit_clone` will return NULL on failure or non-NULL on
-success.
+`hashkit_create` and `hashkit_clone` will return nullptr on failure or pointer
+to `hashkit_st` on success.
 
 `hashkit_is_allocated` returns true if the memory for the hashkit object was
 allocated inside of `hashkit_create` or `hashkit_clone`, otherwise it is false

diff --git a/docs/source/libhashkit/hashkit_function.rst b/docs/source/libhashkit/hashkit_function.rst
index 79b1efea8da268dee981ea17f6bf1fbb9a3bd700..b55f3fb9f1c2f04a01c989cdc77efd90b61c794e 100644 (file)
--- a/docs/source/libhashkit/hashkit_function.rst
+++ b/docs/source/libhashkit/hashkit_function.rst
@@ -9,17 +9,100 @@ SYNOPSIS
 
 .. type:: uint32_t (*hashkit_hash_fn)(const char *key, size_t key_length, void *context)
 
+    :param key: the key to generate a hash of
+    :param key_length: the length of the `key` without any terminating zero byte
+    :param context: the custom hash function context set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`
+    :returns: the custom hash function should return a hash value for `key` as an unsigned 32bit integer
+
+.. c:type:: enum hashkit_return_t hashkit_return_t
+
+.. enum:: hashkit_return_t
+
+    .. enumerator:: HASHKIT_SUCCESS
+
+        Operation succeeded.
+
+    .. enumerator:: HASHKIT_FAILURE
+
+        Operation failed.
+
+    .. enumerator:: HASHKIT_MEMORY_ALLOCATION_FAILURE
+
+        Memory allocation failed.
+
+    .. enumerator:: HASHKIT_INVALID_HASH
+
+        Invalid `hashkit_hash_algorithm_t` passed.
+
+    .. enumerator:: HASHKIT_INVALID_ARGUMENT
+
+        Invalid argument passed.
+
+.. c:type:: enum hashkit_hash_algorithm_t hashkit_hash_algorithm_t
+
+.. enum:: hashkit_hash_algorithm_t
+
+    .. enumerator:: HASHKIT_HASH_DEFAULT
+
+        Default hash algorithm (one_at_a_time).
+
+    .. enumerator:: HASHKIT_HASH_MD5
+    .. enumerator:: HASHKIT_HASH_CRC
+    .. enumerator:: HASHKIT_HASH_FNV1_64
+    .. enumerator:: HASHKIT_HASH_FNV1A_64
+    .. enumerator:: HASHKIT_HASH_FNV1_32
+    .. enumerator:: HASHKIT_HASH_FNV1A_32
+    .. enumerator:: HASHKIT_HASH_HSIEH
+
+        Only available if `libhashkit` hash been built with HSIEH support.
+
+    .. enumerator:: HASHKIT_HASH_MURMUR
+
+        Only available if `libhashkit` has been built with MURMUR support.
+
+    .. enumerator:: HASHKIT_HASH_MURMUR3
+
+        Only available if `libhashkit` has been built with MURMUR support.
+
+    .. enumerator:: HASHKIT_HASH_JENKINS
+    .. enumerator:: HASHKIT_HASH_CUSTOM
+
+        Use custom `hashkit_hash_fn` function set through `hashkit_set_custom_function` or `hashkit_set_custom_distribution_function`.
+
 .. function:: hashkit_return_t hashkit_set_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm)
 
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :param hash_algorithm: valid `hashkit_hash_algorithm_t` constant
+    :returns: `hashkit_return_t` indicating success or failure
+
 .. function:: hashkit_return_t hashkit_set_custom_function(hashkit_st *hash, hashkit_hash_fn function, void *context)
 
+    :param hash: pointer to initialized `hashkit_st` struct
+    :param function: `hashkit_hash_fn` function pointer to use as hash function for `HASHKIT_HASH_CUSTOM`
+    :param context: pointer to an opaque user managed context for the custom hash function
+    :returns: `hashkit_return_t` indicating success or failure
+
 .. function:: hashkit_hash_algorithm_t hashkit_get_function(const hashkit_st *hash)
 
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :returns: `hashkit_hash_algorithm_t` indicating the currently set hash algorithm to use
+
 .. function:: hashkit_return_t hashkit_set_distribution_function(hashkit_st *hash, hashkit_hash_algorithm_t hash_algorithm)
 
-.. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *self, hashkit_hash_fn function, void *context)
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :param hash_algorithm: valid `hashkit_hash_algrothm_t` constant
+    :returns: `hashkit_return_t` indicating success or failure
+
+.. function:: hashkit_return_t hashkit_set_custom_distribution_function(hashkit_st *hash, hashkit_hash_fn function, void *context)
+
+    :param hash: pointer to initialized `hashkit_st` struct
+    :param function: `hashkit_hash_fn` function pointer to use as distribution hash function for `HASHKIT_HASH_CUSTOM`
+    :param context: pointer to an opaque user managed context for the custom distribution hash function
+
+.. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *hash)
 
-.. function:: hashkit_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *self)
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :returns: `hashkit_hash_algorithm_t` indicating the currently set distribution hash algorithm to use
 
 DESCRIPTION
 -----------
@@ -30,7 +113,7 @@ RETURN VALUE
 ------------
 
 `hashkit_set_function`, `hashkit_set_custom_function` and the distribution
-equivalents return `hashkit_return_t` `HASHKIT_SUCCESS` on success.
+equivalents return `hashkit_return_t::HASHKIT_SUCCESS` on success.
 
 `hashkit_get_function` and `hashkit_get_distribution_function` return
 `hashkit_hash_algorithm_t` indicating the hash function used.

diff --git a/docs/source/libhashkit/hashkit_functions.rst b/docs/source/libhashkit/hashkit_functions.rst
index 04f6ba2b24f16f94d30c13e29f6f21d16fc64b9f..9eccb0609fbb340b57f239314691df136e26d25f 100644 (file)
--- a/docs/source/libhashkit/hashkit_functions.rst
+++ b/docs/source/libhashkit/hashkit_functions.rst
@@ -33,11 +33,12 @@ DESCRIPTION
 -----------
 
 These functions generate hash values from a key using a variety of
-algorithms. These functions can be used standalone, or as arguments
-to :func:`hashkit_set_hash_fn` or :func:`hashkit_set_continuum_hash_fn`.
+algorithms. These functions can be used standalone, or will be used
+according to the algorithm set with `hashkit_set_function`
+or `hashkit_set_distribution_function`.
 
-The :func:`hashkit_hsieh` is only available if the library is built with
-the appropriate flag enabled.
+The `hashkit_hsieh`, `hashkit_murmur` and `hashkit_murmur3` functions are
+only available if the library is built with the appropriate flag enabled.
 
 RETURN VALUE
 ------------

diff --git a/docs/source/libhashkit/hashkit_value.rst b/docs/source/libhashkit/hashkit_value.rst
index 1522b4401c4989aef64afd8efade5d7da2f42a51..101630c72179c437e4234be325c321689d73e6cf 100644 (file)
--- a/docs/source/libhashkit/hashkit_value.rst
+++ b/docs/source/libhashkit/hashkit_value.rst
@@ -9,6 +9,10 @@ SYNOPSIS
 
 .. function:: uint32_t hashkit_value(hashkit_st *hash, const char *key, size_t key_length)
 
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :param key: the key to genereate a hash of
+    :param key_length: the length of the `key` without any terminating zero byte
+
 DESCRIPTION
 -----------