docs: libhashkit

[awesomized/libmemcached] / docs / source / libhashkit / hashkit_function.rst

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.