X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fsource%2Flibhashkit%2Fhashkit_function.rst;h=e18f7d5076b4ade2ed7d8cba3e81817f219d0727;hb=1e080e086eed966bfbb1278f7afd24aa9ee27811;hp=d98dedac0bd81130e5fbc206dffd9896eda5d739;hpb=28c4d79e109e11d7d2a9f3189de57da28302ec68;p=awesomized%2Flibmemcached

diff --git a/docs/source/libhashkit/hashkit_function.rst b/docs/source/libhashkit/hashkit_function.rst
index d98dedac..e18f7d50 100644
--- a/docs/source/libhashkit/hashkit_function.rst
+++ b/docs/source/libhashkit/hashkit_function.rst
@@ -1,11 +1,6 @@
 Set Hash Function
 =================
 
-.. index:: object: hashkit_st
-.. index:: object: hashkit_hash_fn
-
-Set hash functions to use for calculating values for keys
-
 SYNOPSIS
 --------
 
@@ -14,32 +9,114 @@ 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_hash_algorithm_t hashkit_get_distribution_function(const hashkit_st *self)
+.. 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)
+
+    :param hash: pointer to an initialized `hashkit_st` struct
+    :returns: `hashkit_hash_algorithm_t` indicating the currently set distribution hash algorithm to use
 
 DESCRIPTION
 -----------
 
 These functions are used to set and retrieve the key and distribution hash functions.
 
-
 RETURN VALUE
 ------------
 
-:func:`hashkit_set_function`, :func:`hashkit_set_custom_function` and the distribution equivalents
-return :type:`hashkit_return_t` `HASHKIT_SUCCESS` on success.
+`hashkit_set_function`, `hashkit_set_custom_function` and the distribution
+equivalents return `hashkit_return_t::HASHKIT_SUCCESS` on success.
 
-:func:`hashkit_get_function` and :func:`hashkit_get_distribution_function` return :type:`hashkit_hash_algorithm_t`
-indicating the hash function used.
+`hashkit_get_function` and `hashkit_get_distribution_function` return
+`hashkit_hash_algorithm_t` indicating the hash function used.
 
 SEE ALSO
 --------
@@ -52,7 +129,7 @@ SEE ALSO
 
 .. only:: html
 
-    * :doc:`../libhashkit`
+    * :doc:`index`
     * :doc:`hashkit_create`
     * :doc:`hashkit_functions`