Documentation: More complete command docblocks

APPEND
clearLastError
DBSIZE
DECR[BY]
DEL

[skip ci]

6 files changed, 162 insertions, 6 deletions

diff --git a/redis.stub.php b/redis.stub.php
index c0ff8e26..2593f367 100644
--- a/redis.stub.php
+++ b/redis.stub.php
@@ -150,6 +150,26 @@ class Redis {
 
     public function acl(string $subcmd, string ...$args): mixed;
 
+    /**
+     * Append data to a Redis STRING key.
+     *
+     * @param string $key   The key in question
+     * @param mixed $value  The data to append to the key.
+     *
+     * @return Redis|int|false The new string length of the key or false on failure.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->set('foo', 'hello);
+     * var_dump($redis->append('foo', 'world'));
+     *
+     * // --- OUTPUT ---
+     * // int(10)
+     * ?>
+     * </code>
+     */
     public function append(string $key, mixed $value): Redis|int|false;
 
     /**
@@ -391,6 +411,22 @@ class Redis {
      *
      * @return bool This should always return true or throw an exception if we're not connected.
      *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->set('string', 'this_is_a_string');
+     * $redis->smembers('string');
+     *
+     * var_dump($redis->getLastError());
+     * $redis->clearLastError();
+     * var_dump($redis->getLastError());
+     *
+     * // --- OUTPUT ---
+     * // string(65) "WRONGTYPE Operation against a key holding the wrong kind of value"
+     * // NULL
+     * ?>
+     * </code>
      */
     public function clearLastError(): bool;
 
@@ -428,14 +464,116 @@ class Redis {
 
     public function copy(string $src, string $dst, array $options = null): Redis|bool;
 
-    public function dbSize(): Redis|int;
+    /**
+     * Return the number of keys in the currently selected Redis database.
+     *
+     * @see https://redis.io/commands/dbsize
+     *
+     * @return Redis|int The number of keys or false on failure.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->flushdb();
+     *
+     * $redis->set('foo', 'bar');
+     * var_dump($redis->dbsize());
+     *
+     * $redis->mset(['a' => 'a', 'b' => 'b', 'c' => 'c', 'd' => 'd']);
+     * var_dump($redis->dbsize());
+     *
+     * // --- OUTPUT
+     * // int(1)
+     * // int(5)
+     * ?>
+     */
+    public function dbSize(): Redis|int|false;
 
     public function debug(string $key): Redis|string;
 
+    /**
+     * Decrement a Redis integer by 1 or a provided value.
+     *
+     * @param string $key The key to decrement
+     * @param int    $by  How much to decrement the key.  Note that if this value is
+     *                    not sent or is set to `1`, PhpRedis will actually invoke
+     *                    the 'DECR' command.  If it is any value other than `1`
+     *                    PhpRedis will actually send the `DECRBY` command.
+     *
+     * @return Redis|int|false The new value of the key or false on failure.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * $redis->set('counter', 3);
+     *
+     * var_dump($redis->decr('counter'));
+     * var_dump($redis->decr('counter', 2));
+     *
+     * // --- OUTPUT ---
+     * // int(2)
+     * // int(0)
+     * ?>
+     * </code>
+     */
     public function decr(string $key, int $by = 1): Redis|int|false;
 
+    /**
+     * Decrement a redis integer by a value
+     *
+     * @param string $key   The integer key to decrement.
+     * @param int    $value How much to decrement the key.
+     *
+     * @return Redis|int|false The new value of the key or false on failure.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost');
+     *
+     * $redis->set('counter', 3);
+     * var_dump($redis->decrby('counter', 1));
+     * var_dump($redis->decrby('counter', 2));
+     *
+     * // --- OUTPUT ---
+     * // int(2)
+     * // int(0)
+     * ?>
+     * </code>
+     */
     public function decrBy(string $key, int $value): Redis|int|false;
 
+    /**
+     * Delete one or more keys from Redis.
+     *
+     * @see https://redis.io/commands/del
+     *
+     * @param array|string $key_or_keys Either an array with one or more key names or a string with
+     *                                  the name of a key.
+     * @param string       $other_keys  One or more additional keys passed in a variadic fashion.
+     *
+     * This method can be called in two distinct ways.  The first is to pass a single array
+     * of keys to delete, and the second is to pass N arguments, all names of keys.  See
+     * below for an example of both strategies.
+     *
+     * <code>
+     * <?php
+     * $redis = new Redis(['host' => 'localhost']);
+     *
+     * for ($i = 0; $i < 5; $i++) {
+     *     $redis->set("key:$i", "val:$i");
+     * }
+     *
+     * var_dump($redis->del('key:0', 'key:1'));
+     * var_dump($redis->del(['key:2', 'key:3', 'key:4']));
+     *
+     * // --- OUTPUT ---
+     * // int(2)
+     * // int(3)
+     * ?>
+     * </code>
+     */
     public function del(array|string $key, string ...$other_keys): Redis|int|false;
 
     /**
diff --git a/redis_arginfo.h b/redis_arginfo.h
index 4e6e20b9..1d09f27e 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: dbcafdb797bd3a4a656d0e1708715bba10ed7f94 */
+ * Stub hash: d9cbe3fdc3c4cd1b079427a54ff2b24ac1c21adc */
 
 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")
@@ -147,7 +147,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_copy, 0, 2, Redi
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, options, IS_ARRAY, 0, "null")
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_dbSize, 0, 0, Redis, MAY_BE_LONG)
+ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_dbSize, 0, 0, Redis, MAY_BE_LONG|MAY_BE_FALSE)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX(arginfo_class_Redis_debug, 0, 1, Redis, MAY_BE_STRING)
diff --git a/redis_cluster.stub.php b/redis_cluster.stub.php
index e968185d..65cdf57d 100644
--- a/redis_cluster.stub.php
+++ b/redis_cluster.stub.php
@@ -51,6 +51,9 @@ class RedisCluster {
 
     public function acl(string|array $key_or_address, string $subcmd, string ...$args): mixed;
 
+    /**
+     * @see Redis::append()
+     */
     public function append(string $key, mixed $value): RedisCluster|bool|int;
 
     public function bgrewriteaof(string|array $key_or_address): RedisCluster|bool;
@@ -108,6 +111,9 @@ class RedisCluster {
      */
     public function lmpop(array $keys, string $from, int $count = 1): RedisCluster|array|null|false;
 
+    /**
+     * @see Redis::clearlasterror()
+     */
     public function clearlasterror(): bool;
 
     public function client(string|array $key_or_address, string $subcommand, ?string $arg = NULL): array|string|bool;
@@ -120,14 +126,26 @@ class RedisCluster {
 
     public function config(string|array $key_or_address, string $subcommand, mixed ...$extra_args): mixed;
 
+    /**
+     * @see Redis::dbsize()
+     */
     public function dbsize(string|array $key_or_address): RedisCluster|int;
 
+    /**
+     * @see Redis::decr()
+     */
     public function decr(string $key, int $by = 1): RedisCluster|int|false;
 
+    /**
+     * @see Redis::decrby()
+     */
     public function decrby(string $key, int $value): RedisCluster|int|false;
 
     public function decrbyfloat(string $key, float $value): float;
 
+    /**
+     * @see Redis::del()
+     */
     public function del(array|string $key, string ...$other_keys): RedisCluster|int|false;
 
     public function discard(): bool;
diff --git a/redis_cluster_arginfo.h b/redis_cluster_arginfo.h
index 7fea6bb5..16096996 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: cb1fe939ac54b2c0e5de0c354fc4a6118336de61 */
+ * Stub hash: fb0623f92a600a7b3cba70d9f3ba82164914f267 */
 
 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 5ee913e8..9122cd6f 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: cb1fe939ac54b2c0e5de0c354fc4a6118336de61 */
+ * Stub hash: fb0623f92a600a7b3cba70d9f3ba82164914f267 */
 
 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 84388245..c8c5d4bf 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: dbcafdb797bd3a4a656d0e1708715bba10ed7f94 */
+ * Stub hash: d9cbe3fdc3c4cd1b079427a54ff2b24ac1c21adc */
 
 ZEND_BEGIN_ARG_INFO_EX(arginfo_class_Redis___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, options)