Documentation: More command docblocks

3 files changed, 225 insertions, 20 deletions

diff --git a/redis.stub.php b/redis.stub.php
index 4f62d731..9030ee57 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -641,6 +641,40 @@ class Redis {
 
     public function discard(): Redis|bool;
 
+    //public function restore(string $key, int $timeout, string $value, ?array $options = NULL): bool;
+    /**
+     * Dump Redis' internal binary representation of a key.
+     *
+     * @see https://redis.io/commands/dump
+     *
+     * @param string $key The key to dump.
+     *
+     * @return Redis|string A binary string representing the key's value.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('zset');
+     *
+     * $redis->zadd('zset', 0, 'zero', 1, 'one', 2, 'two');
+     *
+     * // Retrieve the binary representation of the zset
+     * $binary = $redis->dump('zset');
+     *
+     * // Retore it to a different name
+     * $redis->restore('new-zset', 0, $binary);
+     *
+     * // Array
+     * // (
+     * //     [zero] => 0
+     * //     [one] => 1
+     * //     [two] => 2
+     * // )
+     * $redis->zRange('new-zset', 0, -1, true);
+     * ?>
+     * </code>
+     */
     public function dump(string $key): Redis|string;
 
     /**
@@ -1216,21 +1250,46 @@ class Redis {
      */
     public function rPop(string $key, int $count = 0): Redis|array|string|bool;
 
-    /** @return string|Redis */
-    public function randomKey();
+    /**
+     * Return a random key from the current database
+     *
+     * @see https://redis.io/commands/randomkey
+     *
+     * @return Redis|string|false A random key name or false if no keys exist
+     *
+     */
+    public function randomKey(): Redis|string|false;
 
     public function rawcommand(string $command, mixed ...$args): mixed;
 
-    /** @return bool|Redis */
-    public function rename(string $key_src, string $key_dst);
+    /**
+     * Rename a key
+     *
+     * @param string $old_name The original name of the key
+     * @param string $new_name The new name for the key
+     *
+     * @return Redis|bool True if the key was renamed or false if not.
+     */
+    public function rename(string $old_name, string $new_name): Redis|bool;
 
     /** @return bool|Redis */
     public function renameNx(string $key_src, string $key_dst);
 
-    public function reset(): bool;
+    /**
+     * Reset the state of the connection.
+     *
+     * @return Redis|bool Should always return true unless there is an error.
+     */
+    public function reset(): Redis|bool;
 
     public function restore(string $key, int $timeout, string $value, ?array $options = NULL): bool;
 
+    /**
+     * Query whether the connected instance is a primary or replica
+     *
+     * @return mixed Will return an array with the role of the connected instance unless there is
+     *               an error.
+     */
     public function role(): mixed;
 
     /**
@@ -1415,6 +1474,32 @@ class Redis {
      */
     public function sInter(array|string $key, string ...$other_keys): Redis|array|false;
 
+    /**
+     * Compute the intersection of one or more sets and return the cardinality of the result.
+     *
+     * @see https://redis.io/commands/sintercard
+     *
+     * @param array $keys  One or more set key names.
+     * @param int   $limit A maximum cardinality to return.  This is useful to put an upper bound
+     *                     on the amount of work Redis will do.
+     *
+     * @return Redis|int|false The
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('set1', 'set2', 'set3');
+     *
+     * $redis->sAdd('set1', 'apple', 'pear', 'banana', 'carrot');
+     * $redis->sAdd('set2', 'apple',         'banana');
+     * $redis->sAdd('set3',          'pear', 'banana');
+     *
+     * // int(1)
+     * var_dump($redis->sInterCard(['set1', 'set2', 'set3']));
+     * ?>
+     * </code>
+     */
     public function sintercard(array $keys, int $limit = -1): Redis|int|false;
 
     /**
@@ -1446,6 +1531,36 @@ class Redis {
      */
     public function sInterStore(array|string $key, string ...$other_keys): Redis|int|false;
 
+    /**
+     * Retrieve every member from a set key.
+     *
+     * @see https://redis.io/commands/smembers
+     *
+     * @param string $key The set name.
+     *
+     * @return Redis|array|false Every element in the set or false on failure.
+     *
+     * <code>
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('tng-crew');
+     *
+     * $redis->sAdd('tng-crew', ...['Picard', 'Riker', 'Data', 'Worf', 'La Forge', 'Troi', 'Crusher', 'Broccoli']);
+     *
+     * // Array
+     * // (
+     * //     [0] => Riker
+     * //     [1] => Crusher
+     * //     [2] => Troi
+     * //     [3] => Worf
+     * //     [4] => LaForge
+     * //     [5] => Picard
+     * //     [6] => Broccoli
+     * //     [7] => Data
+     * // )
+     * $redis->sMembers('tng-crew');
+     * </code>
+     */
     public function sMembers(string $key): Redis|array|false;
 
     public function sMisMember(string $key, string $member, string ...$other_members): array;
@@ -1613,6 +1728,38 @@ class Redis {
      */
     public function scard(string $key): Redis|int|false;
 
+    /**
+     * An administrative command used to interact with LUA scripts stored on the server.
+     *
+     * @see https://redis.io/commands/script
+     *
+     * @param string $command The script suboperation to execute.
+     * @param mixed  $args    One ore more additional argument
+     *
+     * @return mixed This command returns various things depending on the specific operation executed.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $lua = sprintf("return %f", microtime(true));
+     *
+     * // array(1) {
+     * //   [0]=>
+     * //   int(0)
+     * // }
+     * var_dump($redis->script('exists', sha1($lua)));
+     *
+     * $redis->script('load', $lua);
+     *
+     * // array(1) {
+     * //   [0]=>
+     * //   int(1)
+     * // }
+     * var_dump($redis->script('exists', sha1($lua)));
+     * ?>
+     * </code>
+     */
     public function script(string $command, mixed ...$args): mixed;
 
     /**
@@ -2366,15 +2513,35 @@ class Redis {
      */
     public function unsubscribe(array $channels): Redis|array|bool;
 
-    /** @return bool|Redis */
-    public function unwatch();
+    /**
+     * Remove any previously WATCH'ed keys in a transaction.
+     *
+     * @see https://redis.io/commands/unwatch
+     * @see https://redis.io/commands/unwatch
+     * @see Redis::watch()
+     *
+     * @return True on success and false on failure.
+     */
+    public function unwatch(): Redis|bool;
 
     /**
      * @return bool|Redis
      */
     public function watch(array|string $key, string ...$other_keys);
 
-    public function wait(int $count, int $timeout): int|false;
+    /**
+     * Block the client up to the provided timeout until a certain number of replicas have confirmed
+     * recieving them.
+     *
+     * @see https://redis.io/commands/wait
+     *
+     * @param int $numreplicas The number of replicas we want to confirm write operaions
+     * @param int $timeout     How long to wait (zero meaning forever).
+     *
+     * @return Redis|int|false The number of replicas that have confirmed or false on failure.
+     *
+     */
+    public function wait(int $numreplicas, int $timeout): int|false;
 
     public function xack(string $key, string $group, array $ids): int|false;
 
@@ -2425,6 +2592,37 @@ class Redis {
     public function xgroup(string $operation, string $key = null, string $group = null, string $id_or_consumer = null,
                            bool $mkstream = false, int $entries_read = -2): mixed;
 
+    /**
+     * Retrieve information about a stream key.
+     *
+     * @param string $operation The specific info operation to perform.
+     * @param string $arg1      The first argument (depends on operation)
+     * @param string $arg2      The second argument
+     * @param int    $count     The COUNT argument to `XINFO STREAM`
+     *
+     * @return mixed This command can return different things depending on the operation being called.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->del('stream');
+     *
+     * $redis->xAdd('stream', "0-1", ['payload' => '0-1']);
+     * $redis->xAdd('stream', "0-2", ['payload' => '0-2']);
+     * $redis->xAdd('stream', "0-3", ['payload' => '0-3']);
+     *
+     * // Retrieve any consmers for a given key
+     * $redis->xInfo('CONSUMERS', 'stream');
+     *
+     * // Retrieve any groups for a given key
+     * $redis->xInfo('GROUPS', 'stream');
+     *
+     * // Retrieve general stream information along with messages
+     * $redis->xInfo('STREAM', 'stream');
+     * ?>
+     * </code>
+     */
     public function xinfo(string $operation, ?string $arg1 = null, ?string $arg2 = null, int $count = -1): mixed;
 
 
diff --git a/redis_arginfo.h b/redis_arginfo.h
index 3016d22f..47dd0584 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: 52904ef54aa9857103e3bb65c089cf09833c507c */
+ * Stub hash: ceb169a872a3df211ded811c1a5ac102832a9158 */
 
 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")
@@ -650,21 +650,25 @@ ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_rPop, 0, 1, Redi
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, count, IS_LONG, 0, "0")
 ZEND_END_ARG_INFO()
 
-#define arginfo_class_Redis_randomKey arginfo_class_Redis___destruct
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_randomKey, 0, 0, Redis, MAY_BE_STRING|MAY_BE_FALSE)
+ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_Redis_rawcommand, 0, 1, IS_MIXED, 0)
 	ZEND_ARG_TYPE_INFO(0, command, IS_STRING, 0)
 	ZEND_ARG_VARIADIC_TYPE_INFO(0, args, IS_MIXED, 0)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_rename, 0, 0, 2)
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_rename, 0, 2, Redis, MAY_BE_BOOL)
+	ZEND_ARG_TYPE_INFO(0, old_name, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, new_name, IS_STRING, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_renameNx, 0, 0, 2)
 	ZEND_ARG_TYPE_INFO(0, key_src, IS_STRING, 0)
 	ZEND_ARG_TYPE_INFO(0, key_dst, IS_STRING, 0)
 ZEND_END_ARG_INFO()
 
-#define arginfo_class_Redis_renameNx arginfo_class_Redis_rename
-
-#define arginfo_class_Redis_reset arginfo_class_Redis_clearLastError
+#define arginfo_class_Redis_reset arginfo_class_Redis_bgSave
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_Redis_restore, 0, 3, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO(0, key, IS_STRING, 0)
@@ -861,7 +865,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_unsubscribe, 0,
 	ZEND_ARG_TYPE_INFO(0, channels, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
-#define arginfo_class_Redis_unwatch arginfo_class_Redis___destruct
+#define arginfo_class_Redis_unwatch arginfo_class_Redis_bgSave
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_watch, 0, 0, 1)
 	ZEND_ARG_TYPE_MASK(0, key, MAY_BE_ARRAY|MAY_BE_STRING, NULL)
@@ -869,7 +873,7 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_watch, 0, 0, 1)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_class_Redis_wait, 0, 2, MAY_BE_LONG|MAY_BE_FALSE)
-	ZEND_ARG_TYPE_INFO(0, count, IS_LONG, 0)
+	ZEND_ARG_TYPE_INFO(0, numreplicas, IS_LONG, 0)
 	ZEND_ARG_TYPE_INFO(0, timeout, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
diff --git a/redis_legacy_arginfo.h b/redis_legacy_arginfo.h
index e91caa8d..5c9e4c3d 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: 52904ef54aa9857103e3bb65c089cf09833c507c */
+ * Stub hash: ceb169a872a3df211ded811c1a5ac102832a9158 */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)
@@ -558,12 +558,15 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_rawcommand, 0, 0, 1)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_rename, 0, 0, 2)
+	ZEND_ARG_INFO(0, old_name)
+	ZEND_ARG_INFO(0, new_name)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_renameNx, 0, 0, 2)
 	ZEND_ARG_INFO(0, key_src)
 	ZEND_ARG_INFO(0, key_dst)
 ZEND_END_ARG_INFO()
 
-#define arginfo_class_Redis_renameNx arginfo_class_Redis_rename
-
 #define arginfo_class_Redis_reset arginfo_class_Redis___destruct
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_restore, 0, 0, 3)
@@ -733,7 +736,7 @@ ZEND_END_ARG_INFO()
 #define arginfo_class_Redis_watch arginfo_class_Redis_del
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis_wait, 0, 0, 2)
-	ZEND_ARG_INFO(0, count)
+	ZEND_ARG_INFO(0, numreplicas)
 	ZEND_ARG_INFO(0, timeout)
 ZEND_END_ARG_INFO()