Merge pull request #2588 from dwdougherty/doc-2601-resp3-replies

Add RESP3 reply schemas to commands
redis · Nov 3, 2023 · 49a8284 · 49a8284
2 parents 1df0c2f + 9d29e0c
commit 49a8284
Show file tree

Hide file tree

Showing 340 changed files with 2,742 additions and 1,737 deletions.
diff --git a/README.md b/README.md
@@ -41,16 +41,49 @@ into account:
     These keywords will get expanded and auto-linked to relevant parts of the
     documentation.
 
-There should be at least two predefined sections: description and return value.
-The return value section is marked using the @return keyword:
+Each command will have a description and both RESP2 and RESP3 return values.
+Regarding the return values, these are contained in the files:
 
-```
-Returns all keys matching the given pattern.
+* `resp2_replies.json`
+* `resp3_replies.json`
 
-@return
+Each file is a dictionary with a matching set of keys. Each key is an array of strings that,
+when processed, produce Markdown content. Here's an example:
 
-@multi-bulk-reply: all the keys that matched the pattern.
 ```
+{
+  ...
+  "ACL CAT": [
+    "One of the following:",
+    "* [Array reply](/docs/reference/protocol-spec#arrays): an array of [Bulk string reply](/docs/reference/protocol-spec#bulk-strings) elements representing ACL categories or commands in a given category.",
+    "* [Simple error reply](/docs/reference/protocol-spec#simple-errors): the command returns an error if an invalid category name is given."
+  ],
+  ...
+}
+```
+
+**Important**: when adding or editing return values, be sure to edit both files. Use the following
+links for the reply type. Note: do not use `@reply-type` specifiers; use only the Markdown link.
+
+```md
+@simple-string-reply: [Simple string reply](https://redis.io/docs/reference/protocol-spec#simple-strings)
+@simple-error-reply: [Simple error reply](https://redis.io/docs/reference/protocol-spec#simple-errors)
+@integer-reply: [Integer reply](https://redis.io/docs/reference/protocol-spec#integers)
+@bulk-string-reply: [Bulk string reply](https://redis.io/docs/reference/protocol-spec#bulk-strings)
+@array-reply: [Array reply](https://redis.io/docs/reference/protocol-spec#arrays)
+@nil-reply: [Nil reply](https://redis.io/docs/reference/protocol-spec#bulk-strings)
+@null-reply: [Null reply](https://redis.io/docs/reference/protocol-spec#nulls)
+@boolean-reply: [Boolean reply](https://redis.io/docs/reference/protocol-spec#booleans)
+@double-reply: [Double reply](https://redis.io/docs/reference/protocol-spec#doubles)
+@big-number-reply: [Big number reply](https://redis.io/docs/reference/protocol-spec#big-numbers)
+@bulk-error-reply: [Bulk error reply](https://redis.io/docs/reference/protocol-spec#bulk-errors)
+@verbatim-string-reply: [Verbatim string reply](https://redis.io/docs/reference/protocol-spec#verbatim-strings)
+@map-reply: [Map reply](https://redis.io/docs/reference/protocol-spec#maps)
+@set-reply: [Set reply](https://redis.io/docs/reference/protocol-spec#sets)
+@push-reply: [Push reply](https://redis.io/docs/reference/protocol-spec#pushes)
+```
+
+**Note:** RESP3 return schemas are not currently included in the `resp2/resp3_replies.json` files for Redis Stack modules.
 
 ## Styling guidelines
 

diff --git a/commands/acl-cat.md b/commands/acl-cat.md
@@ -76,7 +76,3 @@ Then we may want to know what commands are part of a given category:
 30) "psync"
 31) "sort"
 ```
-
-@return
-
-@array-reply: a list of ACL categories or a list of commands inside a given category. The command may return an error if an invalid category name is given as argument.
diff --git a/commands/acl-deluser.md b/commands/acl-deluser.md
@@ -4,10 +4,6 @@ removed from the system, this is the default user that every new connection
 is authenticated with. The list of users may include usernames that do not
 exist, in such case no operation is performed for the non existing users.
 
-@return
-
-@integer-reply: The number of users that were deleted. This number will not always match the number of arguments since certain users may not exist.
-
 @examples
 
 ```

diff --git a/commands/acl-dryrun.md b/commands/acl-dryrun.md
@@ -1,11 +1,6 @@
 Simulate the execution of a given command by a given user.
 This command can be used to test the permissions of a given user without having to enable the user or cause the side effects of running the command.
 
-@return
-
-@simple-string-reply: `OK` on success.
-@bulk-string-reply: An error describing why the user can't execute the command.
-
 @examples
 
 ```

diff --git a/commands/acl-genpass.md b/commands/acl-genpass.md
@@ -25,10 +25,6 @@ rounded to the next multiple of 4. So for instance asking for just 1
 bit password will result in 4 bits to be emitted, in the form of a single
 hex character.
 
-@return
-
-@bulk-string-reply: by default 64 bytes string representing 256 bits of pseudorandom data. Otherwise if an argument if needed, the output string length is the number of specified bits (rounded to the next multiple of 4) divided by 4.
-
 @examples
 
 ```

diff --git a/commands/acl-getuser.md b/commands/acl-getuser.md
@@ -9,10 +9,6 @@ Note: This description of command rules reflects the user's effective permission
 
 Selectors are listed in the order they were applied to the user, and include information about commands, key patterns, and channel patterns.
 
-@array-reply: a list of ACL rule definitions for the user.
-
-If `user` does not exist a @nil-reply is returned.
-
 @examples
 
 Here's an example configuration for a user

diff --git a/commands/acl-help.md b/commands/acl-help.md
@@ -1,5 +1,2 @@
 The `ACL HELP` command returns a helpful text describing the different subcommands.
 
-@return
-
-@array-reply: a list of subcommands and their descriptions
diff --git a/commands/acl-list.md b/commands/acl-list.md
@@ -4,10 +4,6 @@ same used in the redis.conf file or the external ACL file, so you can
 cut and paste what is returned by the ACL LIST command directly inside a
 configuration file if you wish (but make sure to check `ACL SAVE`).
 
-@return
-
-An array of strings.
-
 @examples
 
 ```

diff --git a/commands/acl-load.md b/commands/acl-load.md
@@ -6,12 +6,6 @@ sure to have an *all or nothing* behavior, that is:
 * If every line in the file is valid, all the ACLs are loaded.
 * If one or more line in the file is not valid, nothing is loaded, and the old ACL rules defined in the server memory continue to be used.
 
-@return
-
-@simple-string-reply: `OK` on success.
-
-The command may fail with an error for several reasons: if the file is not readable, if there is an error inside the file, and in such case the error will be reported to the user in the error. Finally the command will fail if the server is not configured to use an external ACL file.
-
 @examples
 
 ```

diff --git a/commands/acl-log.md b/commands/acl-log.md
@@ -8,16 +8,6 @@ The optional argument specifies how many entries to show. By default
 up to ten failures are returned. The special `RESET` argument clears the log.
 Entries are displayed starting from the most recent.
 
-@return
-
-When called to show security events:
-
-@array-reply: a list of ACL security events.
-
-When called with `RESET`:
-
-@simple-string-reply: `OK` if the security log was cleared.
-
 @examples
 
 ```

diff --git a/commands/acl-save.md b/commands/acl-save.md
@@ -1,12 +1,6 @@
 When Redis is configured to use an ACL file (with the `aclfile` configuration
 option), this command will save the currently defined ACLs from the server memory to the ACL file.
 
-@return
-
-@simple-string-reply: `OK` on success.
-
-The command may fail with an error for several reasons: if the file cannot be written or if the server is not configured to use an external ACL file.
-
 @examples
 
 ```

diff --git a/commands/acl-setuser.md b/commands/acl-setuser.md
@@ -84,12 +84,6 @@ This is a list of all the supported Redis ACL rules:
 * `clearselectors`: (Available in Redis 7.0 and later) Deletes all of the selectors attached to the user.
 * `reset`: Removes any capability from the user. They are set to off, without passwords, unable to execute any command, unable to access any key.
 
-@return
-
-@simple-string-reply: `OK` on success.
-
-If the rules contain errors, the error is returned.
-
 @examples
 
 ```

diff --git a/commands/acl-users.md b/commands/acl-users.md
@@ -1,10 +1,6 @@
 The command shows a list of all the usernames of the currently configured
 users in the Redis ACL system.
 
-@return
-
-An array of strings.
-
 @examples
 
 ```

diff --git a/commands/acl-whoami.md b/commands/acl-whoami.md
@@ -2,10 +2,6 @@ Return the username the current connection is authenticated with.
 New connections are authenticated with the "default" user. They
 can change user using `AUTH`.
 
-@return
-
-@bulk-string-reply: the username of the current connection.
-
 @examples
 
 ```

diff --git a/commands/append.md b/commands/append.md
@@ -3,10 +3,6 @@ end of the string.
 If `key` does not exist it is created and set as an empty string, so `APPEND`
 will be similar to `SET` in this special case.
 
-@return
-
-@integer-reply: the length of the string after the append operation.
-
 @examples
 
 ```cli

diff --git a/commands/asking.md b/commands/asking.md
@@ -4,7 +4,3 @@ This is normally done automatically by cluster clients.
 If an `-ASK` redirect is received during a transaction, only one ASKING command needs to be sent to the target node before sending the complete transaction to the target node.
 
 See [ASK redirection in the Redis Cluster Specification](/topics/cluster-spec#ask-redirection) for details.
-
-@return
-
-@simple-string-reply: `OK`.
diff --git a/commands/auth.md b/commands/auth.md
@@ -30,7 +30,3 @@ Because of the high performance nature of Redis, it is possible to try
 a lot of passwords in parallel in very short time, so make sure to generate a
 strong and very long password so that this attack is infeasible.
 A good way to generate strong passwords is via the `ACL GENPASS` command.
-
-@return
-
-@simple-string-reply or an error if the password, or username/password pair, is invalid.
diff --git a/commands/bgrewriteaof.md b/commands/bgrewriteaof.md
@@ -23,8 +23,3 @@ Please refer to the [persistence documentation][tp] for detailed information.
 
 [tp]: /topics/persistence
 
-@return
-
-@simple-string-reply: A simple string reply indicating that the rewriting started or is about to start ASAP, when the call is executed with success.
-
-The command may reply with an error in certain cases, as documented above.
diff --git a/commands/bgsave.md b/commands/bgsave.md
@@ -19,6 +19,3 @@ Please refer to the [persistence documentation][tp] for detailed information.
 
 [tp]: /topics/persistence
 
-@return
-
-@simple-string-reply: `Background saving started` if `BGSAVE` started correctly or `Background saving scheduled` when used with the `SCHEDULE` subcommand. 
diff --git a/commands/bitcount.md b/commands/bitcount.md
@@ -15,12 +15,6 @@ We can use an additional argument `BIT` to specify a bit index.
 So 0 is the first bit, 1 is the second bit, and so forth.
 For negative values, -1 is the last bit, -2 is the penultimate, and so forth.
 
-@return
-
-@integer-reply
-
-The number of bits set to 1.
-
 @examples
 
 ```cli

diff --git a/commands/bitfield.md b/commands/bitfield.md
@@ -78,12 +78,6 @@ By default, **WRAP** is used if not otherwise specified.
     1) (integer) 0
     2) (integer) 3
 
-## Return value
-
-The command returns an array with each entry being the corresponding result of
-the sub command given at the same position. `OVERFLOW` subcommands don't count
-as generating a reply.
-
 The following is an example of `OVERFLOW FAIL` returning NULL.
 
     > BITFIELD mykey OVERFLOW FAIL incrby u2 102 1

diff --git a/commands/bitfield_ro.md b/commands/bitfield_ro.md
@@ -13,7 +13,3 @@ See original `BITFIELD` for more details.
 ```
 BITFIELD_RO hello GET i8 16
 ```
-
-@return
-
-@array-reply: An array with each entry being the corresponding result of the subcommand given at the same position.
diff --git a/commands/bitop.md b/commands/bitop.md
@@ -24,13 +24,6 @@ zero-padded up to the length of the longest string.
 The same holds true for non-existent keys, that are considered as a stream of
 zero bytes up to the length of the longest string.
 
-@return
-
-@integer-reply
-
-The size of the string stored in the destination key, that is equal to the
-size of the longest input string.
-
 @examples
 
 ```cli

diff --git a/commands/bitpos.md b/commands/bitpos.md
@@ -22,20 +22,6 @@ bit, -2 is the penultimate, and so forth.
 
 Non-existent keys are treated as empty strings.
 
-@return
-
-@integer-reply
-
-The command returns the position of the first bit set to 1 or 0 according to the request.
-
-If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.
-
-If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value `0xff` the command `BITPOS key 0` will return 24, since up to bit 23 all the bits are 1.
-
-Basically, the function considers the right of the string as padded with zeros if you look for clear bits and specify no range or the _start_ argument **only**.
-
-However, this behavior changes if you are looking for clear bits and specify a range with both __start__ and __end__. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.
-
 @examples
 
 ```cli

diff --git a/commands/blmove.md b/commands/blmove.md
@@ -10,11 +10,6 @@ This command comes in place of the now deprecated `BRPOPLPUSH`. Doing
 
 See `LMOVE` for more information.
 
-@return
-
-@bulk-string-reply: the element being popped from `source` and pushed to `destination`.
-If `timeout` is reached, a @nil-reply is returned.
-
 ## Pattern: Reliable queue
 
 Please see the pattern description in the `LMOVE` documentation.

diff --git a/commands/blmpop.md b/commands/blmpop.md
@@ -6,10 +6,3 @@ When all lists are empty, Redis will block the connection until another client p
 A `timeout` of zero can be used to block indefinitely.
 
 See `LMPOP` for more information.
-
-@return
-
-@array-reply: specifically:
-
-* A `nil` when no element could be popped, and timeout is reached.
-* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of elements.
diff --git a/commands/blpop.md b/commands/blpop.md
@@ -82,15 +82,6 @@ thing that happens when the timeout is reached.
 If you like science fiction, think of time flowing at infinite speed inside a
 `MULTI` / `EXEC` block...
 
-@return
-
-@array-reply: specifically:
-
-* A `nil` multi-bulk when no element could be popped and the timeout expired.
-* A two-element multi-bulk with the first element being the name of the key
-  where an element was popped and the second element being the value of the
-  popped element.
-
 @examples
 
 ```

diff --git a/commands/brpop.md b/commands/brpop.md
@@ -10,15 +10,6 @@ the tail of a list instead of popping from the head.
 
 [cb]: /commands/blpop
 
-@return
-
-@array-reply: specifically:
-
-* A `nil` multi-bulk when no element could be popped and the timeout expired.
-* A two-element multi-bulk with the first element being the name of the key
-  where an element was popped and the second element being the value of the
-  popped element.
-
 @examples
 
 ```

diff --git a/commands/brpoplpush.md b/commands/brpoplpush.md
@@ -7,11 +7,6 @@ A `timeout` of zero can be used to block indefinitely.
 
 See `RPOPLPUSH` for more information.
 
-@return
-
-@bulk-string-reply: the element being popped from `source` and pushed to `destination`.
-If `timeout` is reached, a @nil-reply is returned.
-
 ## Pattern: Reliable queue
 
 Please see the pattern description in the `RPOPLPUSH` documentation.

diff --git a/commands/bzmpop.md b/commands/bzmpop.md
@@ -6,11 +6,3 @@ When all sorted sets are empty, Redis will block the connection until another cl
 A `timeout` of zero can be used to block indefinitely.
 
 See `ZMPOP` for more information.
-
-@return
-
-@array-reply: specifically:
-
-* A `nil` when no element could be popped.
-* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of the popped elements. Every entry in the elements array is also an array that contains the member and its score.
-
Original file line number	Diff line number	Diff line change
Expand Up		@@ -19,6 +19,3 @@ Please refer to the [persistence documentation][tp] for detailed information.

		[tp]: /topics/persistence

		@return

		@simple-string-reply: `Background saving started` if `BGSAVE` started correctly or `Background saving scheduled` when used with the `SCHEDULE` subcommand.
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,7 +13,3 @@ See original `BITFIELD` for more details. @@
     ```
     BITFIELD_RO hello GET i8 16
     ```
-    @return
-    @array-reply: An array with each entry being the corresponding result of the subcommand given at the same position.