From: Michael Wallner <mike@php.net>
Date: Tue, 4 Aug 2020 15:06:10 +0000 (+0200)
Subject: docs: flush libmemcached progress
X-Git-Tag: 1.1.0-beta1~250^2~1
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=52027f889cdd7435ae3cba934f190996ad739a3a;p=awesomized%2Flibmemcached

docs: flush libmemcached progress
---

diff --git a/docs/source/libmemcached/configuration.rst b/docs/source/libmemcached/configuration.rst
index 8e9c4763..2bd67d55 100644
--- a/docs/source/libmemcached/configuration.rst
+++ b/docs/source/libmemcached/configuration.rst
@@ -9,8 +9,18 @@ SYNOPSIS
 
 .. function:: memcached_st *memcached(const char *string, size_t string_length)
 
+    :param string: configuration string
+    :param string_length: length of the configuration string without any terminating zero
+    :returns: allocated and initialized `memcached_st` struct
+
 .. function:: memcached_return_t libmemcached_check_configuration(const char *option_string, size_t length, char *error_buffer, size_t error_buffer_size)
 
+    :param option_string: configuration string
+    :param length: length of the configuration string without any terminating zero
+    :param error_buffer: buffer used to store any error message
+    :param error_buffer_size: available size of the `error_buffer`
+    :returns: `memcached_return_t` indicating success
+
 DESCRIPTION
 -----------
 
@@ -191,7 +201,7 @@ ENVIRONMENT
 RETURN VALUE
 ------------
 
-`memcached` returns a pointer to the memcached_st that was created (or
+`memcached` returns a pointer to the `memcached_st` that was created (or
 initialized).  On an allocation failure, it returns NULL.
 
 EXAMPLE 
diff --git a/docs/source/libmemcached/constants.rst b/docs/source/libmemcached/constants.rst
index 0952a418..7379d2c0 100644
--- a/docs/source/libmemcached/constants.rst
+++ b/docs/source/libmemcached/constants.rst
@@ -13,8 +13,8 @@ SYNOPSIS
 
 .. c:macro:: LIBMEMCACHED_VERSION_HEX
 
-    Hex value of the version number. "0x00048000" This can be used for comparing
-    versions based on number.
+    Hex value of the version number, e.g. "0x00048000".
+    This can be used for comparing versions based on number.
 
 
 .. c:macro:: MEMCACHED_DEFAULT_PORT
diff --git a/docs/source/libmemcached/index.rst b/docs/source/libmemcached/index.rst
index 478284ad..7f1adabe 100644
--- a/docs/source/libmemcached/index.rst
+++ b/docs/source/libmemcached/index.rst
@@ -33,6 +33,6 @@ libmemcached API
 
 .. toctree:
     :titlesonly:
-    :caption: Misc
+    :caption: Miscellaneous
 
     index_misc
diff --git a/docs/source/libmemcached/memcached_analyze.rst b/docs/source/libmemcached/memcached_analyze.rst
index 312b42f0..74c7541c 100644
--- a/docs/source/libmemcached/memcached_analyze.rst
+++ b/docs/source/libmemcached/memcached_analyze.rst
@@ -11,6 +11,11 @@ SYNOPSIS
 
 .. function:: memcached_analysis_st *memcached_analyze(memcached_st *ptr, memcached_stat_st *stat, memcached_return_t *error)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param stat: pointer to a `memcached_stat_st` struct to fill
+    :param error: pointer to `memcached_return_t` indicating success
+    :returns: pointer to an allocated and filled out `memcached_analysis_t` struct
+
 DESCRIPTION
 -----------
 
diff --git a/docs/source/libmemcached/memcached_append.rst b/docs/source/libmemcached/memcached_append.rst
index 1a60501f..53c8cce5 100644
--- a/docs/source/libmemcached/memcached_append.rst
+++ b/docs/source/libmemcached/memcached_append.rst
@@ -15,6 +15,17 @@ SYNOPSIS
 
 .. function:: memcached_return_t memcached_append_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param group_key: key namespace
+    :param group_key_length: length of the key namespace without any terminating zero
+    :param key: the key
+    :param key_length: length of the key without any terminating zero
+    :param value: the value to append/prepend
+    :param value_length: the length of the value without any terminating zero
+    :param expiration: expiration as a unix timestamp or as relative expiration time in seconds
+    :param flags: 16 bit flags
+    :returns: `memcached_return_t` indicating success
+
 DESCRIPTION
 -----------
 
@@ -22,9 +33,9 @@ DESCRIPTION
 server. All methods take a ``key``, and ``key_length`` to store the object. Keys
 are currently limited to 250 characters when using either a version of memcached
 which is 1.4 or below, or when using the text protocol. You must supply both a
-value and a length. Optionally you may test an expiration time for the object
-and a 16 byte value (it is meant to be used as a bitmap). ``flags`` is a 4byte
-space that is stored alongside of the main value. Many sub libraries make use of
+value and a length. Optionally you may set an expiration time for the object
+and a 16 bit value (it is meant to be used as a bitmap). ``flags`` is a 4 byte
+space that is stored along the main value. Many sub libraries make use of
 this field, so in most cases users should avoid making use of it.
 
 `memcached_prepend` places a segment of data before the last piece of data
@@ -34,7 +45,7 @@ stored. Currently expiration and key are not used in the server.
 stored. Currently expiration and key are not used in the server.
 
 `memcached_prepend_by_key` and `memcached_append_by_key` methods both behave in
-a similar method as the non key methods. The difference is that they use their
+a similar manner as the non key methods. The difference is that they use their
 group_key parameter to map objects to particular servers.
 
 If you are looking for performance, `memcached_set` with non-blocking IO is the
diff --git a/docs/source/libmemcached/memcached_auto.rst b/docs/source/libmemcached/memcached_auto.rst
index 6d1acc88..de8bd092 100644
--- a/docs/source/libmemcached/memcached_auto.rst
+++ b/docs/source/libmemcached/memcached_auto.rst
@@ -15,7 +15,7 @@ SYNOPSIS
 
 .. function:: memcached_return_t memcached_decrement_with_initial (memcached_st *ptr, const char *key, size_t key_length, uint64_t offset, uint64_t initial, time_t expiration, uint64_t *value)
 
-.. function::  memcached_return_t memcached_increment_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, uint32_t offset, uint64_t *value)
+.. function:: memcached_return_t memcached_increment_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, uint32_t offset, uint64_t *value)
 
 .. function:: memcached_return_t memcached_decrement_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, uint32_t offset, uint64_t *value)
 
@@ -23,6 +23,16 @@ SYNOPSIS
 
 .. function:: memcached_return_t memcached_decrement_with_initial_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, uint64_t offset, uint64_t initial, time_t expiration, uint64_t *value)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param group_key: key namespace
+    :param group_key_length: length of the key namespace without any terminating zero
+    :param key: the key
+    :param key_length: length of the key without any terminating zero
+    :param offset: offset to increment/decrement
+    :param initial: initial value if `key` does not exist and `expiration` is not `MEMCACHED_EXPIRATION_NOT_ADD`
+    :param expiration: expiration as a unix timestamp or as relative expiration time in seconds
+    :param value: the resulting value after initialization/increment/decrement
+    :returns: `memcached_return_t` indicating success
 
 DESCRIPTION
 -----------
diff --git a/docs/source/libmemcached/memcached_behavior.rst b/docs/source/libmemcached/memcached_behavior.rst
index bd9998a3..f8353d20 100644
--- a/docs/source/libmemcached/memcached_behavior.rst
+++ b/docs/source/libmemcached/memcached_behavior.rst
@@ -3,8 +3,6 @@ Behaviors of the library
 
 Manipulate the behavior of a memcached_st structure. 
 
-.. index:: object: memcached_st
-
 SYNOPSIS
 --------
 
@@ -13,13 +11,22 @@ SYNOPSIS
 
 .. function:: uint64_t memcached_behavior_get (memcached_st *ptr, memcached_behavior_t flag)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param flag: `memcached_behavior_t` to query
+    :returns: the vaue set for `flag`
+
 .. function:: memcached_return_t memcached_behavior_set (memcached_st *ptr, memcached_behavior_t flag, uint64_t data)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param flag: `memcached_behavior_t` to set
+    :param data: the value to set for `flag`
+    :returns: `memcached_return_t` indicating success
+
     .. versionchanged:: 0.17
-        The `data` argument of `memcached_behavior_set` was changed in
+        The `data` argument of `memcached_behavior_set` was changed
         from taking a pointer to data value, to taking a uin64_t.
 
-.. type:: enum memcached_behavior_t memcached_behavior_t
+.. c:type:: enum memcached_behavior_t memcached_behavior_t
 
 .. enum:: memcached_behavior_t
 
@@ -76,39 +83,23 @@ SYNOPSIS
 
     .. enumerator:: MEMCACHED_BEHAVIOR_TCP_NODELAY
 
-        Turns on the no-delay feature for connecting sockets (may be faster in
-        some environments).
+        Disables Nagle's algorithm.
+        See `RFC 896 <https://tools.ietf.org/html/rfc896>`_.
 
     .. enumerator:: MEMCACHED_BEHAVIOR_HASH
 
-        Set the hash algorithm used for keys.
-
-        The value can be set to either:
-
-        * `MEMCACHED_HASH_DEFAULT`,
-        * `MEMCACHED_HASH_MD5`,
-        * `MEMCACHED_HASH_CRC`,
-        * `MEMCACHED_HASH_FNV1_64`,
-        * `MEMCACHED_HASH_FNV1A_64`,
-        * `MEMCACHED_HASH_FNV1_32`,
-        * `MEMCACHED_HASH_FNV1A_32`,
-        * `MEMCACHED_HASH_JENKINS`,
-        * `MEMCACHED_HASH_HSIEH`, and
-        * `MEMCACHED_HASH_MURMUR`.
+        Set the `hash algorithm <memcached_hash_t>` used for keys.
 
         Each hash has its advantages and its weaknesses. If you don't know or
         don't care, just go with the default.
 
-        Support for `MEMCACHED_HASH_HSIEH` is a compile time option that is
-        disabled by default. To enable tests for this hashing algorithm,
-        configure and build libmemcached with the Hsieh hash enabled.
-
     .. enumerator:: MEMCACHED_BEHAVIOR_DISTRIBUTION
 
-        Using this you can enable different means of distributing values to
-        servers.
+        Setting a `memcached_server_distribution_t` you can enable different
+        means of distributing values to servers.
 
-        The default method is `MEMCACHED_DISTRIBUTION_MODULA`.
+        The default method is `MEMCACHED_DISTRIBUTION_MODULA` (hash of the
+        key modulo number of servers).
 
         You can enable consistent hashing by setting
         `MEMCACHED_DISTRIBUTION_CONSISTENT`. Consistent hashing delivers better
@@ -145,17 +136,7 @@ SYNOPSIS
 
     .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_HASH
 
-        Sets the hashing algorithm for host mapping on continuum.
-
-        The value can be set to either:
-
-        * `MEMCACHED_HASH_DEFAULT`,
-        * `MEMCACHED_HASH_MD5`,
-        * `MEMCACHED_HASH_CRC`,
-        * `MEMCACHED_HASH_FNV1_64`,
-        * `MEMCACHED_HASH_FNV1A_64`,
-        * `MEMCACHED_HASH_FNV1_32`, and
-        * `MEMCACHED_HASH_FNV1A_32`.
+        Sets the `hashing algorithm <memcached_hash_t>` for host mapping on continuum.
 
     .. enumerator:: MEMCACHED_BEHAVIOR_KETAMA_COMPAT
 
@@ -272,7 +253,7 @@ SYNOPSIS
     .. enumerator:: MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
 
         Specify time, in seconds, to mark a connection as idle. This is only
-        available as an option Linux.
+        available as an option on Linux.
 
     .. enumerator:: MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
 
@@ -326,6 +307,39 @@ SYNOPSIS
         server by hash. See `MEMCACHED_CALLBACK_NAMESPACE` for additional
         information.
 
+.. c:type:: enum memcached_server_distribution_t memcached_server_distribution_t
+
+.. enum:: memcached_server_distribution_t
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_MODULA
+
+        Distribute keys by hash modulo number of servers.
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT
+
+        Alias for `MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA`.
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
+
+        Unweighted consistent key distribution.
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_RANDOM
+
+        Distribute keys by :manpage:`rand(3)` modulo number of servers.
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA_SPY
+
+        Unweighted consistent key distribution compatible with the SPY client.
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_CONSISTENT_WEIGHTED
+
+        Weighted consistent key distribution.
+
+    .. enumerator:: MEMCACHED_DISTRIBUTION_VIRTUAL_BUCKET
+
+        Consistent key distribution by virtual buckets.
+
+
 DESCRIPTION
 -----------
 
diff --git a/docs/source/libmemcached/memcached_callback.rst b/docs/source/libmemcached/memcached_callback.rst
index 805f21a9..af89b174 100644
--- a/docs/source/libmemcached/memcached_callback.rst
+++ b/docs/source/libmemcached/memcached_callback.rst
@@ -8,26 +8,44 @@ SYNOPSIS
   Compile and link with -lmemcached
 
 .. function:: memcached_return_t memcached_callback_set(memcached_st *ptr, memcached_callback_t flag, const void *data)
- 
+
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param flag: `memcached_callback_t` flag to set
+    :param data: data corresponding to `flag`
+    :returns: `memcached_return_t` indicating success
+
 .. function:: void *memcached_callback_get(memcached_st *ptr, memcached_callback_t flag, memcached_return_t *error)
 
-.. type:: enum memcached_callback_t memcached_callback_t
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param flag: `memcached_callback_t` flag to query
+    :param error: pointer to `memcached_return_t` indicating success
+    :returns: the `data` previously set
+
+.. c:type:: enum memcached_callback_t memcached_callback_t
  
 .. enum:: memcached_callback_t
 
     .. enumerator:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION
      
-        When `memcached_delete` is called this function will be executed. At the
-        point of its execution all connections are closed.
+        When `memcached_free` or `memcached_reset` is called this function
+        will be executed. At the point of its execution all connections are closed.
+
+        Its signature is:
+
+        .. type:: memcached_return_t (*memcached_cleanup_fn)(const memcached_st *ptr)
+
 
     .. enumerator:: MEMCACHED_CALLBACK_CLONE_FUNCTION
      
-        When `memcached_delete` is called this function will be executed. At the
-        point of its execution all connections are closed.
+        When `memcached_clone` is called this function will be executed.
+
+        Its signature is:
+
+        .. type:: memcached_return_t (*memcached_clone_fn)(memcached_st *destination, const memcached_st *source)
     
     .. enumerator:: MEMCACHED_CALLBACK_PREFIX_KEY
     
-        See `MEMCACHED_CALLBACK_NAMESPACE`
+        See `MEMCACHED_CALLBACK_NAMESPACE`.
     
     .. enumerator:: MEMCACHED_CALLBACK_NAMESPACE
      
diff --git a/docs/source/libmemcached/memcached_cas.rst b/docs/source/libmemcached/memcached_cas.rst
index 017c658f..ce490b21 100644
--- a/docs/source/libmemcached/memcached_cas.rst
+++ b/docs/source/libmemcached/memcached_cas.rst
@@ -11,6 +11,17 @@ SYNOPSIS
 
 .. function:: memcached_return_t memcached_cas_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags, uint64_t cas)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param group_key: key namespace
+    :param group_key_length: length of the `group_key` without any trailing zero
+    :param key: the key to check
+    :param key_length: the length of the `key` without any trailing zero
+    :param value: the value to set
+    :param value_length: the length of the `value` without any trailing zero
+    :param expiration: expiration time as unix timestamp or relative time in seconds
+    :param flags: 16 bit flags
+    :param cas: the ``cas`` value to compare
+    :returns: `memcached_return_t` indicating success
 
 DESCRIPTION
 -----------
@@ -19,10 +30,6 @@ DESCRIPTION
 still the same in the server. You can get the ``cas`` value of a result by
 calling `memcached_result_cas` on a `memcached_result_st` structure.
 
-At the point that this note was written cas is still buggy in memcached. Turning
-on tests for it in `libmemcached` is optional. Please see `memcached_set` for
-information on how to do this.
-
 `memcached_cas_by_key` method behaves in a similar way as the non key methods.
 The difference is that it uses the ``group_key`` parameter to map objects to
 particular servers.
diff --git a/docs/source/libmemcached/memcached_create.rst b/docs/source/libmemcached/memcached_create.rst
index a5bc6379..4b1fc8ce 100644
--- a/docs/source/libmemcached/memcached_create.rst
+++ b/docs/source/libmemcached/memcached_create.rst
@@ -11,11 +11,22 @@ SYNOPSIS
 
 .. function:: memcached_st* memcached_create(memcached_st *ptr)
 
+    :param ptr: pointer to user-allocated `memcached_st` struct or null pointer
+    :returns: pointer to initialized `memcached_st` struct
+
 .. function:: void memcached_free(memcached_st *ptr)
 
+    :param ptr: pointer to initialized `memcached_st` struct to destroy and possibly free
+
 .. function:: memcached_st* memcached_clone(memcached_st *destination, memcached_st *source)
 
-.. function:: void memcached_servers_reset(memcached_st)
+    :param destination: pointer to user-allocated `memcached_st` struct or null pointer
+    :param source: pointer to initialized `memcached_st` struct to copy from
+    :returns: pointer to newly initialized `destination`, copied from `source`
+
+.. function:: void memcached_servers_reset(memcached_st *ptr)
+
+    :param ptr: pointer to initialized `memcached_st` struct
 
 DESCRIPTION
 -----------
@@ -29,8 +40,8 @@ Please note, when you write new application use `memcached` over
 `memcached_create`.
 
 `memcached_clone` is similar to `memcached_create` but it copies the defaults
-and list of servers from the source `memcached_st`. If you pass a null as the
-argument for the source to clone, it is the same as a call to
+and list of servers from the source `memcached_st` pointer. If you pass a null
+as the argument for the source to clone, it is the same as a call to
 `memcached_create`. If the destination argument is NULL a `memcached_st` will be
 allocated for you.
 
diff --git a/docs/source/libmemcached/memcached_delete.rst b/docs/source/libmemcached/memcached_delete.rst
index f3763090..840f6274 100644
--- a/docs/source/libmemcached/memcached_delete.rst
+++ b/docs/source/libmemcached/memcached_delete.rst
@@ -7,10 +7,17 @@ SYNOPSIS
 #include <libmemcached/memcached.h>
   Compile and link with -lmemcached
 
-.. function:: memcached_return_t memcached_delete (memcached_st *ptr, const char *key, size_t key_length, time_t expiration)
+.. function:: memcached_return_t memcached_delete(memcached_st *ptr, const char *key, size_t key_length, time_t expiration)
 
-.. function:: memcached_return_t memcached_delete_by_key (memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, time_t expiration)
+.. function:: memcached_return_t memcached_delete_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, time_t expiration)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param group_key: key namespace
+    :param group_key_length: length of the `group_key` without any terminating zero
+    :param key: the key to delete
+    :param key_length: the length og the `key` without any terminating zero
+    :param expiration: obsolete since :manpage:`memcached(1)` version 1.4
+    :returns: `memcached_return_t` indicating success
 
 DESCRIPTION
 -----------
diff --git a/docs/source/libmemcached/memcached_dump.rst b/docs/source/libmemcached/memcached_dump.rst
index ec0de8a7..e96c7634 100644
--- a/docs/source/libmemcached/memcached_dump.rst
+++ b/docs/source/libmemcached/memcached_dump.rst
@@ -1,26 +1,34 @@
 Dumping data from a server
 ==========================
 
-Get a list of keys found on memcached servers
-
-.. index:: object: memcached_st
-
 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
+
+.. type:: memcached_return_t (*memcached_dump_fn)(memcached_st *ptr, const char *key, size_t key_length, void *context)
+
+    :param ptr: pointer to `memcached_st` object
+    :param key: key string being dumped
+    :param key_length: length of the key without any terminating zero
+    :param context: pointer to the user supplied context
+    :returns: `memcached_return_t` indicating success
 
 .. function:: memcached_return_t memcached_dump (memcached_st *ptr, memcached_dump_fn *function, void *context, uint32_t number_of_callbacks)
 
-.. type:: memcached_return_t (*memcached_dump_fn)(memcached_st *ptr,  const char *key, size_t key_length, void *context)
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param function: pointer to `number_of_callbacks` `memcached_dump_fn` callbacks
+    :param context: pointer to a user managed context
+    :param number_of_callbacks: number of callbacks in the `function` array
+    :returns: `memcached_return_t` indicating success
 
-Compile and link with -lmemcached
 
 DESCRIPTION
 -----------
 
-:func:`memcached_dump` is used to get a list of keys found in memcached(1)
-servers. Because memcached(1) does not guarantee to dump all keys you can not
+:func:`memcached_dump` is used to get a list of keys found in :manpage:`memcached(1)`
+servers. Because memcached does not guarantee to dump all keys you can not
 assume you have fetched all keys from the server. The function takes an array
 of callbacks that it will use to execute on keys as they are found.
 
@@ -29,7 +37,7 @@ Currently the binary protocol is not tested.
 RETURN VALUE
 ------------
 
-A value of type :type:`memcached_return_t` is returned
+A value of type :type:`memcached_return_t` is returned.
 On success that value will be `MEMCACHED_SUCCESS`.
 Use :func:`memcached_strerror` to translate this value to a printable 
 string.
@@ -39,4 +47,11 @@ SEE ALSO
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+
+.. only:: html
+
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
diff --git a/docs/source/libmemcached/memcached_exist.rst b/docs/source/libmemcached/memcached_exist.rst
index 60f5ae2a..d93a2205 100644
--- a/docs/source/libmemcached/memcached_exist.rst
+++ b/docs/source/libmemcached/memcached_exist.rst
@@ -1,19 +1,22 @@
-===========================
-Determine if a keys exists.
-===========================
-
-.. index:: object: memcached_st
+Determine if a keys exists
+==========================
 
 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function::  memcached_return_t memcached_exist(memcached_st *ptr, char *key, size_t *key_length)
 
 .. function::  memcached_return_t memcached_exist_by_key(memcached_st *ptr, char *group_key, size_t *group_key_length, char *key, size_t *key_length)
 
-Compile and link with -lmemcached
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param group_key: the key namespace
+    :param group_key_length: length of the `group_key` without any terminating zero
+    :param key: the key to check
+    :param key_length: length of the `key` without any terminating zero
+    :returns: `memcached_return_t` indicating success
 
 .. versionadded:: 0.53
 
@@ -36,5 +39,12 @@ SEE ALSO
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+
+.. only:: html
 
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
diff --git a/docs/source/libmemcached/memcached_fetch.rst b/docs/source/libmemcached/memcached_fetch.rst
index ae567777..0d58d616 100644
--- a/docs/source/libmemcached/memcached_fetch.rst
+++ b/docs/source/libmemcached/memcached_fetch.rst
@@ -1,41 +1,52 @@
 memcached_fetch
 =================
 
-.. index:: object: memcached_st
-
 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function::  char *memcached_fetch(memcached_st *ptr, char *key, size_t *key_length, size_t *value_length, uint32_t *flags, memcached_return_t *error)
 
    .. deprecated:: 0.50
       Use :func:`memcached_fetch_result` instead.
 
-Compile and link with -lmemcached
 
 DESCRIPTION
 -----------
 
-:func:`memcached_fetch` is used to fetch an individual value from the server. :func:`memcached_mget` must always be called before using this method.
-You must pass in a key and its length to fetch the object. You must supply
-three pointer variables which will give you the state of the returned
-object.  A :type:`uint32_t` pointer to contain whatever flags you stored with the value, a :type:`size_t` pointer which will be filled with size of of the 
-object, and a :type:`memcached_return_t` pointer to hold any error. The 
-object will be returned upon success and NULL will be returned on failure. `MEMCACHED_END` is returned by the \*error value when all objects that have been found are returned. The final value upon `MEMCACHED_END` is null. 
+:func:`memcached_fetch` is used to fetch an individual value from the server.
+:func:`memcached_mget` must always be called before using this method.
+You must pass in a key and its length to fetch the object.
+
+You must supply three pointer variables which will give you the state of the returned
+object:
+
+    * A :type:`uint32_t` pointer to contain whatever flags you stored with the value,
+    * a :type:`size_t` pointer which will be filled with size of of the object, and
+    * a :type:`memcached_return_t` pointer to hold any error.
+
+The object will be returned upon success and NULL will be returned on failure.
+
+`MEMCACHED_END` is returned by the error value when all objects that have been found are returned.
+The final value upon `MEMCACHED_END` is a NULL pointer.
 
 Values returned by :func:`memcached_fetch` must be freed by the caller.
 
 All of the above functions are not tested when the
 `MEMCACHED_BEHAVIOR_USE_UDP` has been set. Executing any of these 
-functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED` being returned, or for those functions which do not return a :type:`memcached_return_t`, the error function parameter will be set to `MEMCACHED_NOT_SUPPORTED`.
+functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED`
+being returned, or for those functions which do not return a
+:type:`memcached_return_t`, the error function parameter will
+be set to `MEMCACHED_NOT_SUPPORTED`.
 
 RETURN VALUE
 ------------
 
 :func:`memcached_fetch` sets error to
 to `MEMCACHED_END` upon successful conclusion.
+
 `MEMCACHED_NOTFOUND` will be return if no keys at all were found.
 
 `MEMCACHED_KEY_TOO_BIG` is set to error whenever :func:`memcached_fetch` was used
@@ -47,5 +58,14 @@ SEE ALSO
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_fetch_result(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+    :manpage:`memcached_fetch_result(3)`
+
+.. only:: html
 
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
+    * :doc:`memcached_get`
diff --git a/docs/source/libmemcached/memcached_flush.rst b/docs/source/libmemcached/memcached_flush.rst
index 52addbb3..342ee1f5 100644
--- a/docs/source/libmemcached/memcached_flush.rst
+++ b/docs/source/libmemcached/memcached_flush.rst
@@ -1,23 +1,22 @@
 Wiping clean the contents of a server
 =====================================
 
-.. index:: object: memcached_st
-
-Wipe contents of memcached servers
-
 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function:: memcached_return_t memcached_flush (memcached_st *ptr, time_t expiration)
 
-Compile and link with -lmemcached
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param expiration: expiration as a unix timestamp or as relative expiration time in seconds
+    :returns: `memcached_return_t` indicating success
 
 DESCRIPTION
 -----------
 
-:func::`memcached_flush` is used to wipe clean the contents of :program:`memcached` servers.
+`memcached_flush` is used to wipe clean the contents of :manpage:`memcached(1)` servers.
 It will either do this immediately or expire the content based on the
 expiration time passed to the method (a value of zero causes an immediate
 flush). The operation is not atomic to multiple servers, just atomic to a
@@ -27,13 +26,21 @@ added.
 RETURN VALUE
 ------------
 
-A value of type :type:`memcached_return_t` is returned
+A value of type :type:`memcached_return_t` is returned.
 On success that value will be `MEMCACHED_SUCCESS`.
-Use :type:`memcached_strerror` to translate this value to a printable string.
+Use `memcached_strerror` to translate this value to a printable string.
 
 SEE ALSO
 --------
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+
+.. only:: html
+
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
diff --git a/docs/source/libmemcached/memcached_flush_buffers.rst b/docs/source/libmemcached/memcached_flush_buffers.rst
index 9e71fb21..85b7aaa8 100644
--- a/docs/source/libmemcached/memcached_flush_buffers.rst
+++ b/docs/source/libmemcached/memcached_flush_buffers.rst
@@ -1,36 +1,44 @@
-Flushing client buffers
-=======================
-
-.. index:: object: memcached_st
-
 Flush and send buffered commands
+================================
 
 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function:: memcached_return_t memcached_flush_buffers (memcached_st *ptr)
 
-Compile and link with -lmemcached
+    :param ptr: pointer to initialized `memcached_st` struct
+    :returns: `memcached_return_t` indicating success
 
 DESCRIPTION
 -----------
 
 :func:`memcached_flush_buffers` is used in conjunction with
-`MEMCACHED_BEHAVIOR_BUFFER_REQUESTS` (see memcached_behavior(3)) to flush all buffers by sending the buffered commands to the server for processing.
+`MEMCACHED_BEHAVIOR_BUFFER_REQUESTS` to flush all buffers by
+sending the buffered commands to the server for processing.
 
 RETURN VALUE
 ------------
 
-A value of type :type:`memcached_return_t` is returned
+A value of type :type:`memcached_return_t` is returned.
 On success that value will be `MEMCACHED_SUCCESS`.
-Use :func:`memcached_strerror` to translate this value to a printable 
-string.
+Use :func:`memcached_strerror` to translate this value to a printable string.
 
 SEE ALSO
 --------
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+    :manpage:`memcached_behavior(3)`
+
+.. only:: html
+
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
+    * :doc:`memcached_behavior`
diff --git a/docs/source/libmemcached/memcached_generate_hash_value.rst b/docs/source/libmemcached/memcached_generate_hash_value.rst
index 2c72cbbc..b1e19e57 100644
--- a/docs/source/libmemcached/memcached_generate_hash_value.rst
+++ b/docs/source/libmemcached/memcached_generate_hash_value.rst
@@ -1,44 +1,57 @@
 Generating hash values directly
 ===============================
 
-.. index:: object: memcached_st
-
 Hash a key value
 
 SYNOPSIS 
 --------
 
 #include <libmemcached/memcached.h>
-
-.. type:: memcached_hash_t
+    Compile and link with -lmemcachedutil -lmemcached
 
 .. function:: uint32_t memcached_generate_hash_value (const char *key, size_t key_length, memcached_hash_t hash_algorithm)
 
+    :param key: the key to generate a hash of
+    :param key_length: the length of the `key` without any terminating zero
+    :param hash_algorithm: `memcached_hash_t`, the algorithm to use
+    :returns: a 32 bit hash value
+
 .. function:: uint32_t memcached_generate_hash (memcached_st *ptr, const char *key, size_t key_length)
 
-.. type:: MEMCACHED_HASH_DEFAULT
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param key: the key to generate a hash of
+    :param key_length: the length of the `key` without any terminating zero
+    :returns: a 32 bit hash value
+
+.. c:type:: enum memcached_hash_t memcached_hash_t
+
+.. enum:: memcached_hash_t
+
+    .. enumerator::  MEMCACHED_HASH_DEFAULT
+
+    .. enumerator::  MEMCACHED_HASH_MD5
+
+    .. enumerator::  MEMCACHED_HASH_CRC
 
-.. type:: MEMCACHED_HASH_MD5
+    .. enumerator::  MEMCACHED_HASH_FNV1_64
 
-.. type:: MEMCACHED_HASH_CRC
+    .. enumerator::  MEMCACHED_HASH_FNV1A_64
 
-.. type:: MEMCACHED_HASH_FNV1_64
+    .. enumerator::  MEMCACHED_HASH_FNV1_32
 
-.. type:: MEMCACHED_HASH_FNV1A_64
+    .. enumerator::  MEMCACHED_HASH_FNV1A_32
 
-.. type:: MEMCACHED_HASH_FNV1_32
+    .. enumerator::  MEMCACHED_HASH_HSIEH
 
-.. type:: MEMCACHED_HASH_FNV1A_32
+    .. enumerator::  MEMCACHED_HASH_MURMUR
 
-.. type:: MEMCACHED_HASH_JENKINS
+    .. enumerator::  MEMCACHED_HASH_JENKINS
 
-.. type:: MEMCACHED_HASH_MURMUR
+    .. enumerator::  MEMCACHED_HASH_MURMUR3
 
-.. type:: MEMCACHED_HASH_HSIEH
+    .. enumerator::  MEMCACHED_HASH_CUSTOM
 
-.. type:: MEMCACHED_HASH_MURMUR3
 
-Compile and link with -lmemcachedutil -lmemcached
 
 DESCRIPTION
 -----------
@@ -48,8 +61,9 @@ the hash functions defined in the library. This method is provided for
 the convenience of higher-level language bindings and is not necessary
 for normal memcache operations.
 
-The allowed hash algorithm constants are listed in the manpage for
-:func:`memcached_behavior_set`.
+Support for `MEMCACHED_HASH_HSIEH` is a compile time option that is
+disabled by default. To enable tests for this hashing algorithm,
+configure and build libmemcached with the Hsieh hash enabled.
 
 :func:`memcached_generate_hash` takes a :type:`memcached_st` structure
 and produces the hash value that would have been generated based on the 
diff --git a/docs/source/libmemcached/memcached_get.rst b/docs/source/libmemcached/memcached_get.rst
index cb4415a2..d14a1a63 100644
--- a/docs/source/libmemcached/memcached_get.rst
+++ b/docs/source/libmemcached/memcached_get.rst
@@ -1,12 +1,11 @@
 Retrieving data from the server
 ===============================
 
-.. index:: object: memcached_st
-
 SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function:: memcached_result_st * memcached_fetch_result (memcached_st *ptr, memcached_result_st *result, memcached_return_t *error)
 
@@ -26,7 +25,6 @@ SYNOPSIS
 
 .. type:: memcached_return_t (*memcached_execute_fn)(const memcached_st *ptr, memcached_result_st *result, void *context)
 
-Compile and link with -lmemcached
 
 DESCRIPTION
 -----------
@@ -34,28 +32,36 @@ DESCRIPTION
 :func:`memcached_get` is used to fetch an individual value from the server.
 You must pass in a key and its length to fetch the object. You must supply
 three pointer variables which will give you the state of the returned
-object.  A :type:`uint32_t` pointer to contain whatever flags you stored with the value, a :type:`size_t` pointer which will be filled with size of of 
+object.  A :type:`uint32_t` pointer to contain whatever flags you stored
+with the value, a :type:`size_t` pointer which will be filled with size of of
 the object, and a :type:`memcached_return_t` pointer to hold any error. The 
 object will be returned upon success and NULL will be returned on failure. Any 
 object returned by :func:`memcached_get` must be released by the caller 
 application.
 
 :func:`memcached_mget` is used to select multiple keys at once. For
-multiple key operations it is always faster to use this function. This function always works asynchronously. 
+multiple key operations it is always faster to use this function.
+This function always works asynchronously.
 
-To retrieve data after a successful execution of :func:`memcached_mget`, you will need to
-call :func:`memcached_fetch_result`.  You should continue to call this function until 
-it returns a NULL (i.e. no more values). If you need to quit in the middle of a
-:func:`memcached_mget` call, you can execute a :func:`memcached_quit`, those this is not required.
+To retrieve data after a successful execution of :func:`memcached_mget`, you
+will need to call :func:`memcached_fetch_result`.  You should continue to call
+this function until it returns a NULL (i.e. no more values). If you need to quit
+in the middle of a :func:`memcached_mget` call, you can execute a
+:func:`memcached_quit`, those this is not required.
 
-:func:`memcached_fetch_result` is used to fetch an individual value from the server. :func:`memcached_mget` must always be called before using this method.
+:func:`memcached_fetch_result` is used to fetch an individual value from the
+server. :func:`memcached_mget` must always be called before using this method.
 You must pass in a key and its length to fetch the object. You must supply
-three pointer variables which will give you the state of the returned
-object.  A :type:`uint32_t` pointer to contain whatever flags you stored with the value, a :type:`size_t` pointer which will be filled with size of of the 
-object, and a :type:`memcached_return_t` pointer to hold any error. The 
-object will be returned upon success and NULL will be returned on failure. `MEMCACHED_END` is returned by the \*error value when all objects that have been found are returned. The final value upon `MEMCACHED_END` is null. 
-
-:func:`memcached_fetch_result` is used to return a :type:`memcached_result_st` structure from a memcached server. The result object is forward compatible
+three pointer variables which will give you the state of the returned object.
+A :type:`uint32_t` pointer to contain whatever flags you stored with the value,
+a :type:`size_t` pointer which will be filled with size of of the object, and a
+:type:`memcached_return_t` pointer to hold any error. The object will be
+returned upon success and NULL will be returned on failure. `MEMCACHED_END` is
+returned by the \*error value when all objects that have been found have been
+returned. The final value upon `MEMCACHED_END` is null.
+
+:func:`memcached_fetch_result` is used to return a :type:`memcached_result_st`
+structure from a memcached server. The result object is forward compatible
 with changes to the server. For more information please refer to the 
 :type:`memcached_result_st` help. This function will dynamically allocate a 
 result structure for you if you do not pass one to the function.
@@ -87,28 +93,39 @@ which server an object was stored if key partitioning was used for storage.
 
 All of the above functions are not tested when the
 `MEMCACHED_BEHAVIOR_USE_UDP` has been set. Executing any of these 
-functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED` being returned, or for those functions which do not return a :type:`memcached_return_t`, the error function parameter will be set to `MEMCACHED_NOT_SUPPORTED`.
+functions with this behavior on will result in `MEMCACHED_NOT_SUPPORTED` being
+returned, or for those functions which do not return a
+:type:`memcached_return_t`, the error function parameter will be set to
+`MEMCACHED_NOT_SUPPORTED`.
 
 RETURN VALUE
 ------------
 
-All objects retrieved via :func:`memcached_get` or :func:`memcached_get_by_key` must be freed with :manpage:`free(3)`.
+All objects retrieved via :func:`memcached_get` or :func:`memcached_get_by_key`
+must be freed with :manpage:`free(3)`.
 
-:func:`memcached_get` will return NULL on
-error. You must look at the value of error to determine what the actual error 
-was.
+:func:`memcached_get` will return NULL on error.
+You must look at the value of error to determine what the actual error was.
 
 :func:`memcached_fetch_execute` return `MEMCACHED_SUCCESS` if
-all keys were successful. `MEMCACHED_NOTFOUND` will be return if no
+all keys were successful. `MEMCACHED_NOTFOUND` will be returned if no
 keys at all were found.
 
 :func:`memcached_fetch_result` sets error
 to `MEMCACHED_END` upon successful conclusion.
-`MEMCACHED_NOTFOUND` will be return if no keys at all were found.
+`MEMCACHED_NOTFOUND` will be returned if no keys at all were found.
 
 SEE ALSO
 --------
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+
+.. only:: html
+
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
diff --git a/docs/source/libmemcached/memcached_last_error.rst b/docs/source/libmemcached/memcached_last_error.rst
index c5ddf490..e135a8f3 100644
--- a/docs/source/libmemcached/memcached_last_error.rst
+++ b/docs/source/libmemcached/memcached_last_error.rst
@@ -7,11 +7,20 @@ SYNOPSIS
 #include <libmemcached/memcached.h>
   Compile and link with -lmemcached
 
-.. function:: memcached_return_t memcached_last_error(const memcached_st *)
+.. function:: memcached_return_t memcached_last_error(const memcached_st *ptr)
 
-.. function:: const char *memcached_last_error_message(const memcached_st *)
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :returns: `memcached_return_t` indicating success of last operation
 
-.. function:: int memcached_last_error_errno(const memcached_st *)
+.. function:: const char *memcached_last_error_message(const memcached_st *ptr)
+
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :returns: message describing the status of last operation
+
+.. function:: int memcached_last_error_errno(const memcached_st *ptr)
+
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :returns: :manpage:`errno(3)` (if any) of last operation
 
 DESCRIPTION
 -----------
@@ -37,11 +46,13 @@ SEE ALSO
 .. only:: man
 
     :manpage:`memcached(1)`
+    :manpage:`errno(3)`
     :manpage:`libmemcached(3)`
     :manpage:`memcached_strerror(3)`
 
 .. only:: html
 
     * :manpage:`memcached(1)`
+    * :manpage:`errno(3)`
     * :doc:`../libmemcached`
     * :doc:`memcached_strerror`
diff --git a/docs/source/libmemcached/memcached_memory_allocators.rst b/docs/source/libmemcached/memcached_memory_allocators.rst
index 9f8f98fd..6bde09bd 100644
--- a/docs/source/libmemcached/memcached_memory_allocators.rst
+++ b/docs/source/libmemcached/memcached_memory_allocators.rst
@@ -11,18 +11,56 @@ SYNOPSIS
 
 .. function:: memcached_return_t memcached_set_memory_allocators (memcached_st *ptr, memcached_malloc_fn mem_malloc, memcached_free_fn mem_free, memcached_realloc_fn mem_realloc, memcached_calloc_fn mem_calloc, void *context)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param mem_malloc: pointer to a `memcached_malloc_fn` callback
+    :param mem_free: pointer to a `memcached_free_fn` callback
+    :param mem_realloc: pointer to a `memcached_realloc_fn` callback
+    :param mem_calloc: pointer to a `memcached_calloc_fn` callback
+    :param context: pointer to a user supplied context
+    :returns: `memcached_return_t` indicating success
+
 .. function:: void memcached_get_memory_allocators (memcached_st *ptr, memcached_malloc_fn *mem_malloc, memcached_free_fn *mem_free, memcached_realloc_fn *mem_realloc, memcached_calloc_fn *mem_calloc)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param mem_malloc: pointer to store the address of the `memcached_malloc_fn` callback
+    :param mem_free: pointer to store the address of the `memcached_free_fn` callback
+    :param mem_realloc: pointer to store the address of the `memcached_realloc_fn` callback
+    :param mem_calloc: pointer to store the address of the `memcached_calloc_fn` callback
+
 .. function:: void * memcached_get_memory_allocators_context(const memcached_st *ptr)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :returns: pointer to the user supplied context
+
 .. type:: void * (*memcached_malloc_fn) (memcached_st *ptr, const size_t size, void *context)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param size: the number of bytes to allocate
+    :param context: pointer to the user supplied context
+    :returns: pointer to at least `size` bytes of allocated memory
+
 .. type:: void * (*memcached_realloc_fn) (memcached_st *ptr, void *mem, const size_t size, void *context)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param mem: pointer to previously allocated memory
+    :param size: the number of bytes to allocate
+    :param context: pointer to the user supplied context
+    :returns: pointer to at least `size` bytes of allocated memory
+
 .. type:: void (*memcached_free_fn) (memcached_st *ptr, void *mem, void *context)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param mem: pointer to previously allocated memory
+    :param context: pointer to the user supplied context
+
 .. type:: void * (*memcached_calloc_fn) (memcached_st *ptr, size_t nelem, const size_t elsize, void *context)
 
+    :param ptr: pointer to an initialized `memcached_st` struct
+    :param nelem: number of elements to allocate
+    :param elsize: the number of bytes to allocate per element
+    :param context: pointer to the user supplied context
+    :returns: pointer to at least `elsize` \* `nelem`  bytes of allocated and zeroed memory
+
 DESCRIPTION
 -----------
 
@@ -51,13 +89,13 @@ NOTES
 -----
 
 In version 0.38 all functions were modified to have a context void pointer
-passed to them. This was so that customer allocators could have their own space
+passed to them. This was so that custom allocators could have their own space
 for memory.
 
 RETURN VALUE
 ------------
 
-:func:`memcached_set_memory_allocators` return `MEMCACHED_SUCCESS` upon success,
+:func:`memcached_set_memory_allocators` returns `MEMCACHED_SUCCESS` upon success,
 and `MEMCACHED_FAILURE` if you don't pass a complete set of function pointers.
 
 SEE ALSO
diff --git a/docs/source/libmemcached/memcached_quit.rst b/docs/source/libmemcached/memcached_quit.rst
index 60e11ae7..3421d47b 100644
--- a/docs/source/libmemcached/memcached_quit.rst
+++ b/docs/source/libmemcached/memcached_quit.rst
@@ -7,17 +7,20 @@ SYNOPSIS
 --------
 
 #include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function:: void memcached_quit (memcached_st *ptr)
 
-Compile and link with -lmemcached
+    :param ptr: pointer to initialized `memcached_st` struct
 
 DESCRIPTION
 -----------
 
 :func:`memcached_quit` will disconnect you from all currently connected
-servers. It will also reset the state of the connection (ie, any :func:`memcached_fetch` you are in the middle of will be terminated). This function is 
-called automatically when you call :func:`memcached_free` on the :type:`memcached_st` structure.
+servers. It will also reset the state of the connection (i.e., any
+:func:`memcached_fetch` you are in the middle of will be terminated). This
+function is called automatically when you call :func:`memcached_free` on the
+:type:`memcached_st` structure.
 
 You do not need to call this on your own. All operations to change server
 hashes and parameters will handle connections to the server for you. This
@@ -36,4 +39,12 @@ SEE ALSO
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+
+.. only:: html
+
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
diff --git a/docs/source/libmemcached/memcached_result_st.rst b/docs/source/libmemcached/memcached_result_st.rst
index fcc00abe..a0471b35 100644
--- a/docs/source/libmemcached/memcached_result_st.rst
+++ b/docs/source/libmemcached/memcached_result_st.rst
@@ -4,49 +4,88 @@ Working with result sets
 SYNOPSIS
 --------
 
-#include <libmemcached/memcached_pool.h>
+#include <libmemcached/memcached.h>
+    Compile and link with -lmemcachedutil -lmemcached
 
-.. type:: memcached_result_st
+.. type:: struct memcached_result_st memcached_result_st
 
-.. function:: memcached_result_st * memcached_result_create (memcached_st *ptr, memcached_result_st *result)
+.. function:: memcached_result_st *memcached_result_create (memcached_st *ptr, memcached_result_st *result)
+
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param result: pointer to an `memcached_result_st` instance to initialize or
+                   nullptr to allocate a new instance
+    :returns: pointer to initialized `memcached_result_st` instance
 
 .. function:: void memcached_result_free (memcached_result_st *result)
 
+    :param result: pointer to initialized `memcached_result_st` struct
+
 .. function:: const char * memcached_result_key_value (memcached_result_st *result)
 
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the key value associated with the current result object
+
 .. function:: size_t memcached_result_key_length (const memcached_result_st *result)
 
-.. function:: const char *memcached_result_value (memcached_result_st *ptr)
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the key length associated with the current result object
+
+.. function:: const char *memcached_result_value (memcached_result_st *result)
+
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the result value associated with the current result object
+
+.. function:: char *memcached_result_take_value (memcached_result_st *result)
+
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the result value associated with the current result object
 
-.. function:: char *memcached_result_take_value (memcached_result_st *ptr)
+.. function:: size_t memcached_result_length (const memcached_result_st *result)
 
-.. function:: size_t memcached_result_length (const memcached_result_st *ptr)
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the result length associated with the current result object
 
 .. function:: uint32_t memcached_result_flags (const memcached_result_st *result)
 
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the flags associated with the current result object
+
 .. function:: uint64_t memcached_result_cas (const memcached_result_st *result)
 
-.. function:: memcached_return_t memcached_result_set_value (memcached_result_st *ptr, const char *value, size_t length)
+    :param result: pointer to initialized `memcached_result_st` struct
+    :returns: the cas associated with the current result object
+
+.. function:: memcached_return_t memcached_result_set_value (memcached_result_st *result, const char *value, size_t length)
+
+    :param result: pointer to initialized `memcached_result_st` struct
+    :param value: byte array to set the value of the current result object to
+    :param length: the length of `value` wothout any terminating zero
+    :returns: `memcached_return_t` indicating success
+
+.. function:: void memcached_result_set_flags (memcached_result_st *result, uint32_t flags)
 
-.. function:: void memcached_result_set_flags (memcached_result_st *ptr, uint32_t flags)
+    :param result: pointer to initialized `memcached_result_st` struct
+    :param flags: a new value for the flags field
 
-.. function:: void memcached_result_set_expiration (memcached_result_st *ptr, time_t)
+.. function:: void memcached_result_set_expiration (memcached_result_st *result, time_t expiration)
+
+    :param result: pointer to initialized `memcached_result_st` struct
+    :param expiration: a new value for the expiration field
 
-Compile and link with -lmemcachedutil -lmemcached
 
 DESCRIPTION
 -----------
 
-libmemcached(3) can optionally return a :type:`memcached_result_st` which
+`libmemcached` can optionally return a :type:`memcached_result_st` which
 acts as a result object. The result objects have added benefits over the 
-character pointer returns, in that they are forward compatible with new 
+character pointer return values, in that they are forward compatible with new
 return items that future memcached servers may implement (the best current 
 example of this is the CAS return item). The structures can also be reused, 
-which will save on calls to malloc(3). It is suggested that you use result 
-objects over char \* return functions.
+which will save on calls to :manpage:`malloc(3)`. It is suggested that you use
+result objects over char \* return functions.
 
 The structure of :type:`memcached_result_st` has been encapsulated, you should
-not write code to directly access members of the structure.
+not write code directly accessing members of the structure.
 
 :func:`memcached_result_create` will either allocate memory for a
 :type:`memcached_result_st` or will initialize a structure passed to it.
@@ -64,9 +103,9 @@ the current result object.
 current result object.
 
 :func:`memcached_result_take_value` returns and hands over the result value
-associated with the current result object. You must call free() to release this
-value, unless you have made use of a custom allocator. Use of a custom
-allocator requires that you create your own custom free() to release it.
+associated with the current result object. You must call :manpage:`free(3)` to
+release this value, unless you have made use of a custom allocator. Use of a
+custom allocator requires that you create your own custom free() to release it.
 
 :func:`memcached_result_length` returns the result length associated with
 the current result object.
@@ -88,9 +127,6 @@ value for the flags field.
 a new value for the expiration field (this is only used by read through
 triggers).
 
-You may wish to avoid using memcached_result_create(3) with a
-stack based allocation. The most common issues related to ABI safety involve
-heap allocated structures.
 
 RETURN VALUE
 ------------
@@ -104,4 +140,14 @@ SEE ALSO
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+    :manpage:`memcached_memory_allocators(3)`
+
+.. only:: html
+
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
+    * :doc:`memcached_memory_allocators`
diff --git a/docs/source/libmemcached/memcached_return_t.rst b/docs/source/libmemcached/memcached_return_t.rst
index 3b34fa00..ed4fbd07 100644
--- a/docs/source/libmemcached/memcached_return_t.rst
+++ b/docs/source/libmemcached/memcached_return_t.rst
@@ -7,13 +7,13 @@ SYNOPSIS
 #include <libmemcached/memcached.h>
   Compile and link with -lmemcached
 
-.. function:: bool memcached_success(memcached_return_t)
+.. function:: bool memcached_success(memcached_return_t rc)
 
 .. function:: bool memcached_continue(memcached_return_t rc)
 
-.. function:: bool memcached_failed(memcached_return_t)
+.. function:: bool memcached_failed(memcached_return_t rc)
 
-.. function:: bool memcached_fatal(memcached_return_t)
+.. function:: bool memcached_fatal(memcached_return_t rc)
 
 .. c:type:: enum memcached_return_t memcached_return_t
 
diff --git a/docs/source/libmemcached/memcached_sasl.rst b/docs/source/libmemcached/memcached_sasl.rst
index e87451ae..e7fbb63f 100644
--- a/docs/source/libmemcached/memcached_sasl.rst
+++ b/docs/source/libmemcached/memcached_sasl.rst
@@ -1,27 +1,38 @@
 SASL support
 ============
 
-.. index:: object: memcached_st
-
 SYNOPSIS
 --------
 
-#include <libmemcached/memcached_pool.h>
+#include <libmemcached/memcached.h>
+    Compile and link with -lmemcached
 
 .. function:: void memcached_set_sasl_callbacks(memcached_st *ptr, const sasl_callback_t *callbacks)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param callbacks: pointer to `sasl_callbacks_t` holding the callbacks to use
+
 .. function:: const sasl_callback_t *memcached_get_sasl_callbacks(memcached_st *ptr)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :returns: pointer to `sasl_callbacks_t` holding the callbacks currently used
+
 .. function:: memcached_return_t memcached_set_sasl_auth_data(memcached_st *ptr, const char *username, const char *password)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :param username:
+    :param password:
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_return_t memcached_destroy_sasl_auth_data(memcached_st *ptr)
 
-Compile and link with -lmemcached
+    :param ptr: pointer to initialized `memcached_st` struct
+    :returns: `memcached_return_t` indicating success
 
 DESCRIPTION
 -----------
 
-libmemcached(3) allows you to plug in your own callbacks function used by
+`libmemcached` allows you to plug in your own callbacks function used by
 libsasl to perform SASL authentication.
 
 Please note that SASL requires the memcached binary protocol, and you have
@@ -30,10 +41,9 @@ to specify the callbacks before you connect to the server.
 :func:`memcached_set_sasl_auth_data` is a helper function defining
 the basic functionality for you, but it will store the username and password
 in memory. If you choose to use this method you have to call
-:type:`memcached_destroy_sasl_auth_data` before calling 
-:type:`memcached_free` to avoid a memory leak. You should NOT call 
-:type:`memcached_destroy_sasl_auth_data` if you specify your own callback 
-function with :func:`memcached_set_sasl_callbacks`.
+`memcached_destroy_sasl_auth_data` before calling `memcached_free` to avoid a
+memory leak. You should NOT call `memcached_destroy_sasl_auth_data` if you
+specify your own callback function with `memcached_set_sasl_callbacks`.
 
 RETURN VALUE
 ------------
@@ -47,4 +57,16 @@ SEE ALSO
 
 .. only:: man
 
-  :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`
+    :manpage:`memcached(1)`
+    :manpage:`libmemcached(3)`
+    :manpage:`memcached_strerror(3)`
+    :manpage:`sasl_client_new(3)`
+    :manpage:`sasl_callbacks(3)`
+
+.. only:: html
+
+    * :manpage:`memcached(1)`
+    * :doc:`../libmemcached`
+    * :doc:`memcached_strerror`
+    * :manpage:`sasl_client_new(3)`
+    * :manpage:`sasl_callbacks(3)`
diff --git a/docs/source/libmemcached/memcached_server_st.rst b/docs/source/libmemcached/memcached_server_st.rst
index faa7c4c9..1ca82c1c 100644
--- a/docs/source/libmemcached/memcached_server_st.rst
+++ b/docs/source/libmemcached/memcached_server_st.rst
@@ -9,14 +9,19 @@ SYNOPSIS
 
 .. c:type:: struct memcached_instance_st memcached_instance_st
 
-.. c:type:: struct memcached_server_list_st memcached_server_list_st
-
 .. c:type:: struct memcached_server_st memcached_server_st
 
+.. c:type:: struct memcached_server_st *memcached_server_list_st
+
 .. function:: const memcached_instance_st * memcached_server_list (memcached_st *ptr)
 
+    :param ptr: pointer to initialized `memcached_st` struct
+    :returns: list of `memcached_instance_st` objects
+
 .. function:: void memcached_server_list_free (memcached_server_list_st list)
 
+    :param list:
+
 .. function:: memcached_server_list_st memcached_server_list_append (memcached_server_list_st list, const char *hostname, in_port_t port, memcached_return_t *error)
 
 .. function:: uint32_t memcached_server_list_count (memcached_server_list_st list)
@@ -36,8 +41,7 @@ DESCRIPTION
 
 libmemcached(3) operates on a list of hosts which are stored in
 :type:`memcached_server_st` structures. You should not modify these structures
-directly. Functions are provided to modify these structures (and more can be
-added, just ask!).
+directly. Functions are provided to modify these structures.
 
 :func:`memcached_server_list` is used to provide an array of all defined hosts. This was incorrectly documented as "requiring free" up till version 0.39.
 
diff --git a/docs/source/libmemcached/memcached_touch.rst b/docs/source/libmemcached/memcached_touch.rst
index b1b982e4..75be550d 100644
--- a/docs/source/libmemcached/memcached_touch.rst
+++ b/docs/source/libmemcached/memcached_touch.rst
@@ -1,6 +1,5 @@
-===========================================
-memcached_touch, memcached_touch_by_key
-===========================================
+Update expiration on a key
+==========================
 
 .. index:: object: memcached_st
 
diff --git a/src/libmemcached/behavior.cc b/src/libmemcached/behavior.cc
index 07ad1c46..36201737 100644
--- a/src/libmemcached/behavior.cc
+++ b/src/libmemcached/behavior.cc
@@ -373,7 +373,7 @@ uint64_t memcached_behavior_get(memcached_st *shell,
     return hashkit_get_function(&ptr->hashkit);
 
   case MEMCACHED_BEHAVIOR_KETAMA_HASH:
-    return hashkit_get_function(&ptr->hashkit);
+    return hashkit_get_distribution_function(&ptr->hashkit);
 
   case MEMCACHED_BEHAVIOR_REMOVE_FAILED_SERVERS:
     return ptr->flags.auto_eject_hosts;