Documentation: Add detailed docblocks for list pop operations.

6 files changed, 78 insertions, 10 deletions

diff --git a/redis.stub.php b/redis.stub.php
index 501cc1e5..42d58abe 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -352,8 +352,37 @@ class Redis {
      */
     public function zmpop(array $keys, string $from, int $count = 1): Redis|array|null|false;
 
+    /**
+     * Pop one or more elements from one or more Redis LISTs, blocking up to a specified timeout when
+     * no elements are available.
+     *
+     * @see https://redis.io/commands/blmpop
+     *
+     * @param float  $timeout The number of seconds Redis will block when no elements are available.
+     * @param array  $keys    One or more Redis LISTs to pop from.
+     * @param string $from    The string 'LEFT' or 'RIGHT' (case insensitive), telling Redis whether
+     *                        to pop elements from the beginning or end of the LISTs.
+     * @param int    $count   Pop up to how many elements at once.
+     *
+     * @return Redis|array|null|false One or more elements popped from the list(s) or false if all LISTs
+     *                                were empty.
+     */
     public function blmpop(float $timeout, array $keys, string $from, int $count = 1): Redis|array|null|false;
 
+    /**
+     * Pop one or more elements off of one or more Redis LISTs.
+     *
+     * @see https://redis.io/commands/lmpop
+     *
+     * @param array  $keys  An array with one or more Redis LIST key names.
+     * @param string $from  The string 'LEFT' or 'RIGHT' (case insensitive), telling Redis whether to pop\
+     *                      elements from the beginning or end of the LISTs.
+     * @param int    $count The maximum number of elements to pop at once.
+     *
+     * @return Redis|array|null|false One or more elements popped from the LIST(s) or false if all the LISTs
+     *                                were empty.
+     *
+     */
     public function lmpop(array $keys, string $from, int $count = 1): Redis|array|null|false;
 
     /**
@@ -849,6 +878,18 @@ class Redis {
 
     public function punsubscribe(array $patterns): Redis|array|bool;
 
+    /**
+     * Pop one or more elements from the end of a Redis LIST.
+     *
+     * @see https://redis.io/commands/rpop
+     *
+     * @param string $key   A redis LIST key name.
+     * @param int    $count The maximum number of elements to pop at once.
+     *
+     * NOTE:  The `count` argument requires Redis >= 6.2.0
+     *
+     * @return Redis|array|string|bool One ore more popped elements or false if all were empty.
+     */
     public function rPop(string $key, int $count = 0): Redis|array|string|bool;
 
     /** @return string|Redis */
@@ -868,7 +909,19 @@ class Redis {
 
     public function role(): mixed;
 
-    public function rpoplpush(string $src, string $dst): Redis|string|false;
+    /**
+     * Atomically pop an element off the end of a Redis LIST and push it to the beginning of
+     * another.
+     *
+     * @see https://redis.io/commands/rpoplpush
+     *
+     * @param string $srckey The source key to pop from.
+     * @param string $dstkey The destination key to push to.
+     *
+     * @return Redis|string|false The popped element or false if the source key was empty.
+     *
+     */
+    public function rpoplpush(string $srckey, string $dstkey): Redis|string|false;
 
     public function sAdd(string $key, mixed $value, mixed ...$other_values): Redis|int|false;
 
diff --git a/redis_arginfo.h b/redis_arginfo.h
index d683a42a..7f638a06 100644
--- a/redis_arginfo.h
+++ b/redis_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 76d56f0a612ec76a5e5f59c90fe09b223f846de6 */
+ * Stub hash: 3c2e612a6892a8ae2ac363336c462e24a1333050 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, options, IS_ARRAY, 0, "null")
@@ -676,8 +676,8 @@ ZEND_END_ARG_INFO()
 #define arginfo_class_Redis_role arginfo_class_Redis_getAuth
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_rpoplpush, 0, 2, Redis, MAY_BE_STRING|MAY_BE_FALSE)
-	ZEND_ARG_TYPE_INFO(0, src, IS_STRING, 0)
-	ZEND_ARG_TYPE_INFO(0, dst, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, srckey, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, dstkey, IS_STRING, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_sAdd, 0, 2, Redis, MAY_BE_LONG|MAY_BE_FALSE)
diff --git a/redis_cluster.stub.php b/redis_cluster.stub.php
index 8a705a16..cd316142 100644
--- a/redis_cluster.stub.php
+++ b/redis_cluster.stub.php
@@ -98,8 +98,14 @@ class RedisCluster {
 
     public function zmpop(array $keys, string $from, int $count = 1): RedisCluster|array|null|false;
 
+    /**
+     * @see Redis::blmpop()
+     */
     public function blmpop(float $timeout, array $keys, string $from, int $count = 1): RedisCluster|array|null|false;
 
+    /**
+     * @see Redis::lmpop()
+     */
     public function lmpop(array $keys, string $from, int $count = 1): RedisCluster|array|null|false;
 
     public function clearlasterror(): bool;
@@ -347,8 +353,14 @@ class RedisCluster {
 
     public function role(string|array $key_or_address): mixed;
 
+    /**
+     * @see Redis::rpop()
+     */
     public function rpop(string $key, int $count = 0): RedisCluster|bool|string|array;
 
+    /**
+     * @see Redis::rpoplpush()
+     */
     public function rpoplpush(string $src, string $dst): RedisCluster|bool|string;
 
     public function rpush(string $key, mixed ...$elements): RedisCluster|int|false;
diff --git a/redis_cluster_arginfo.h b/redis_cluster_arginfo.h
index 7a0f7164..26ed3de7 100644
--- a/redis_cluster_arginfo.h
+++ b/redis_cluster_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 2b379c65c90f7e5e8958bab1b13b3f607fa33c37 */
+ * Stub hash: 84ef1f62ed4ba37f79eab0897519bba0946b0f26 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_RedisCluster___construct, 0, 0, 1)
 	ZEND_ARG_TYPE_INFO(0, name, IS_STRING, 1)
diff --git a/redis_cluster_legacy_arginfo.h b/redis_cluster_legacy_arginfo.h
index f8318b61..3766e125 100644
--- a/redis_cluster_legacy_arginfo.h
+++ b/redis_cluster_legacy_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 2b379c65c90f7e5e8958bab1b13b3f607fa33c37 */
+ * Stub hash: 84ef1f62ed4ba37f79eab0897519bba0946b0f26 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_RedisCluster___construct, 0, 0, 1)
 	ZEND_ARG_INFO(0, name)
diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h
index d53dce66..d08b9276 100644
--- a/redis_legacy_arginfo.h
+++ b/redis_legacy_arginfo.h
@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 76d56f0a612ec76a5e5f59c90fe09b223f846de6 */
+ * Stub hash: 3c2e612a6892a8ae2ac363336c462e24a1333050 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)
@@ -576,8 +576,8 @@ ZEND_END_ARG_INFO()
 #define arginfo_class_Redis_role arginfo_class_Redis___destruct
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_rpoplpush, 0, 0, 2)
-	ZEND_ARG_INFO(0, src)
-	ZEND_ARG_INFO(0, dst)
+	ZEND_ARG_INFO(0, srckey)
+	ZEND_ARG_INFO(0, dstkey)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_sAdd, 0, 0, 2)
@@ -717,7 +717,10 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_subscribe, 0, 0, 2)
 	ZEND_ARG_INFO(0, cb)
 ZEND_END_ARG_INFO()
 
-#define arginfo_class_Redis_swapdb arginfo_class_Redis_rpoplpush
+ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_swapdb, 0, 0, 2)
+	ZEND_ARG_INFO(0, src)
+	ZEND_ARG_INFO(0, dst)
+ZEND_END_ARG_INFO()
 
 #define arginfo_class_Redis_time arginfo_class_Redis___destruct