From: Michael Wallner <mike@php.net>
Date: Thu, 28 May 2020 06:57:56 +0000 (+0200)
Subject: docs: libmemcachedutil
X-Git-Tag: 1.1.0-beta1~250^2~2
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=bd68f254afbf924020f10bd7dcadac8f2aa3affa;p=awesomized%2Flibmemcached

docs: libmemcachedutil
---

diff --git a/docs/source/libmemcachedutil.rst b/docs/source/libmemcachedutil.rst
index fb2e994d..f17cd86b 100644
--- a/docs/source/libmemcachedutil.rst
+++ b/docs/source/libmemcachedutil.rst
@@ -8,7 +8,7 @@ SYNOPSIS
 --------
 
 #include <libmemcachedutil-|libmemcached_version|/util.h>
-  Compile and link with -lmemcachedutil
+  Compile and link with -lmemcachedutil -lmemcached
 
 DESCRIPTION
 -----------
@@ -22,7 +22,7 @@ THREADS AND PROCESSES
 Do not try to access an instance of `memcached_st` from multiple threads at the
 same time. If you want to access memcached from multiple threads you should
 either clone the `memcached_st`, or use the memcached pool implementation. See
-`memcached_pool_create`.
+`memcached_pool`.
 
 SEE ALSO
 --------
diff --git a/docs/source/libmemcachedutil/memcached_pool.rst b/docs/source/libmemcachedutil/memcached_pool.rst
index d089147b..3b954e3a 100644
--- a/docs/source/libmemcachedutil/memcached_pool.rst
+++ b/docs/source/libmemcachedutil/memcached_pool.rst
@@ -11,22 +11,48 @@ SYNOPSIS
 
 .. function:: memcached_pool_st* memcached_pool(const char *option_string, size_t option_string_length)
 
+    :param option_string: :doc:`configuration </libmemcached/configuration>` string
+    :param option_string_length: length of `options_string` without any trailing zero byte
+    :returns: allocated and initialized `memcached_pool_st` instance on success or nullptr on failure
+
 .. function:: memcached_st* memcached_pool_destroy(memcached_pool_st* pool)
 
-.. function:: memcached_st* memcached_pool_fetch(memcached_pool_st*, struct timespec* relative_time, memcached_return_t* rc)
+    :param pool: initialized `memcached_pool_st` instance to free
+    :returns: pointer to the 'master' `memcached_st` instance by legacy
+
+.. function:: memcached_st* memcached_pool_fetch(memcached_pool_st* pool, struct timespec* relative_time, memcached_return_t* rc)
 
     .. versionadded:: 0.53
        Synonym for memcached_pool_pop
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param relative_time: time to block thread and wait for a connection to become available when pool size is exceeded, unless nullptr
+    :param rc: out pointer to `memcached_return_t`
+    :returns: pointer to an available `memcached_st` instance
+
 .. function:: memcached_return_t memcached_pool_release(memcached_pool_st* pool, memcached_st* mmc)
 
     .. versionadded:: 0.53
        Synonym for memcached_pool_push.
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param mmc: the `memcached_st` instance to return to the pool
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_return_t memcached_pool_behavior_set(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t data)
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param flag: the :doc:`behavior </libmemcached/memcached_behavior>` to change
+    :param value: the value to set for `flag`
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_return_t memcached_pool_behavior_get(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t *value)
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param flag: the :doc:`behavior </libmemcached/memcached_behavior>` to read
+    :param value: out pointer to receive the set value of `flag`
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_pool_st* memcached_pool_create(memcached_st* mmc, int initial, int max)
 
     .. deprecated:: 0.46
@@ -81,16 +107,20 @@ pool (or NULL if an allocation cannot be satisfied).
 
 `memcached_pool_release` returns `MEMCACHED_SUCCESS` upon success.
 
-`memcached_pool_behavior_get` and `memcached_pool_behavior_get` returns
+`memcached_pool_behavior_get` and `memcached_pool_behavior_get` return
 `MEMCACHED_SUCCESS` upon success.
 
-If any methods returns MEMCACHED_IN_PROGRESS then a lock on the pool could not
-be obtained. If any of the parameters passed to any of these functions is
-invalid, MEMCACHED_INVALID_ARGUMENTS will be returned.
+`memcached_pool_fetch` may return `MEMCACHED_TIMEOUT` if a timeout occurs while
+waiting for a free `memcached_st` instance, `MEMCACHED_NOTFOUND` if no `memcached_st`
+instance was available, respectively.
+
+.. note::
+    If any method returns `MEMCACHED_IN_PROGRESS` then a lock on the pool could not
+    be obtained.
+
+    If any of the parameters passed to any of these functions is
+    invalid, `MEMCACHED_INVALID_ARGUMENTS` will be returned.
 
-memcached_pool_fetch may return MEMCACHED_TIMEOUT if a timeout occurs while
-waiting for a free memcached_st. MEMCACHED_NOTFOUND if no memcached_st was
-available.
 
 SEE ALSO
 --------