docs: flush libmemcached progress

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 

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

docs/source/libmemcached/index.rst

@@ -33,6 +33,6 @@ libmemcached API
 
 .. toctree:
     :titlesonly:
-    :caption: Misc
+    :caption: Miscellaneous
 
     index_misc

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
 -----------
 

docs/source/libmemcached/memcached_append.rst

@@ -15,16 +15,27 @@ 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
 -----------
 
 `memcached_prepend` and memcached_append are used to modify information on a
 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

docs/source/libmemcached/memcached_auto.rst

@@ -15,14 +15,24 @@ 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)
 
 .. function:: memcached_return_t memcached_increment_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)
 
 .. 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
 -----------

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
 -----------
 

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
 

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.

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.