DEV: add RESP2/3 info to the top-k commands (#1747)

* DEV: add RESP2/3 info to the top-k commands

* Apply suggestions from code review

Co-authored-by: mich-elle-luna <[email protected]>

---------

Co-authored-by: mich-elle-luna <[email protected]>

Author: dwdougherty

content/commands/topk.add.md

@@ -33,25 +33,41 @@ syntax_str: items [items ...]
 title: TOPK.ADD
 ---
 
-Adds an item to the data structure. 
-Multiple items can be added at once.
-If an item enters the Top-K list, the item which is expelled is returned.
-This allows dynamic heavy-hitter detection of items being entered or expelled from Top-K list. 
+Adds an item to a Top-k sketch. 
+Multiple items can be added at the same time.
+If an item enters the Top-K sketch, the item that is expelled (if any) is returned.
+This allows dynamic heavy-hitter detection of items being entered or expelled from Top-K sketch. 
 
-### Parameters
+## Parameters
 
-* **key**: Name of sketch where item is added.
-* **item**: Item/s to be added.
+* **key**: the name of the sketch where items are added.
+* **item**: the items to be added.
 
-### Return
-
-[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) - if an element was dropped from the TopK list, [Nil reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) otherwise..
-
-#### Example
+## Example
 
 ```
 redis> TOPK.ADD topk foo bar 42
 1) (nil)
 2) baz
 3) (nil)
-```
+```
+
+## Return information
+
+{{< multitabs id=“topk-add-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) containing either dropped elements or [nil (null bulk string)]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}).
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments or non-existant key.
+
+-tab-sep-
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) containing either dropped elements or [null]({{< relref "/develop/reference/protocol-spec#nulls" >}}).
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, or key of the incorrect type.
+
+{{< /multitabs >}}

content/commands/topk.count.md

@@ -21,33 +21,29 @@ categories:
 - clients
 complexity: O(n) where n is the number of items
 deprecated_since: '2.4'
-description: Return the count for one or more items are in a sketch
+description: Return the count for one or more items in a sketch
 group: topk
 hidden: false
 linkTitle: TOPK.COUNT
 module: Bloom
 since: 2.0.0
 stack_path: docs/data-types/probabilistic
-summary: Return the count for one or more items are in a sketch
+summary: Return the count for one or more items in a sketch
 syntax_fmt: TOPK.COUNT key item [item ...]
 syntax_str: item [item ...]
 title: TOPK.COUNT
 ---
-Returns count for an item. 
+Returns counts for each item present in the sketch. 
 Multiple items can be requested at once.
-Please note this number will never be higher than the real count and likely to be lower.
+Please note this number will never be higher than the real count and will likely be lower.
 
 This command has been deprecated. The count value is not a representative of
 the number of appearances of an item.
 
-### Parameters
+## Parameters
 
-* **key**: Name of sketch where item is counted.
-* **item**: Item/s to be counted.
-
-## Return
-
-[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}) - count for responding item.
+* **key**: the name of the sketch where items are to be counted.
+* **item**: the items to be counted.
 
 ## Examples
 
@@ -57,3 +53,23 @@ redis> TOPK.COUNT topk foo 42 nonexist
 2) (integer) 1
 3) (integer) 0
 ```
+
+## Return information
+
+{{< multitabs id=“topk-count-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [integer replies]({{< relref "/develop/reference/protocol-spec#integers" >}}) representing the count of each specified item. For non-existant items, `0` is returned.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, or key of the incorrect type.
+
+-tab-sep-
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [integer replies]({{< relref "/develop/reference/protocol-spec#integers" >}}) representing the count of each specified item. For non-existant items, `0` is returned.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, or key of the incorrect type.
+
+{{< /multitabs >}}

content/commands/topk.incrby.md

@@ -38,25 +38,45 @@ syntax_fmt: TOPK.INCRBY key item increment [item increment ...]
 syntax_str: item increment [item increment ...]
 title: TOPK.INCRBY
 ---
-Increase the score of an item in the data structure by increment. 
-Multiple items' score can be increased at once.
-If an item enters the Top-K list, the item which is expelled is returned.
+Increase the score of an item in the data structure by `increment`. 
+Multiple items' scores can be increased at once.
+If an item enters the Top-K list, the item that is expelled (if any) is returned.
 
 ### Parameters
 
-* **key**: Name of sketch where item is added.
-* **item**: Item/s to be added.
-* **increment**: increment to current item score. Increment must be greater or equal to 1. Increment is limited to 100,000 to avoid server freeze.
+* **key**: the name of the sketch.
+* **item**: the items to be incremented.
+* **increment**: the value by which items will be incremented. The `increment` must be greater or equal to 1 and less than or equal to 100,000 to avoid server freeze.
 
 ## Return
 
-[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) - if an element was dropped from the TopK list, [Nil reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) otherwise..
+[Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) - if an element was dropped from the TopK list, [Nil reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) otherwise..
 
-@example
+## Example
 
 ```
 redis> TOPK.INCRBY topk foo 3 bar 2 42 30
 1) (nil)
 2) (nil)
 3) foo
-```
+```
+
+## Return information
+
+{{< multitabs id=“topk-incrby-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) containing either dropped elements or [nil (null bulk string)]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}).
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, key of the incorrect type, or an incorrect increment (less than 0 or greater than 100,000).
+
+-tab-sep-
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) containing either dropped elements or [null]({{< relref "/develop/reference/protocol-spec#nulls" >}}).
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, key of the incorrect type, or an incorrect increment (less than 0 or greater than 100,000).
+
+{{< /multitabs >}}

content/commands/topk.info.md

@@ -29,15 +29,11 @@ syntax_fmt: TOPK.INFO key
 syntax_str: ''
 title: TOPK.INFO
 ---
-Returns number of required items (k), width, depth and decay values.
+Returns number of required items (k), width, depth, and decay values of a given sketch.
 
-### Parameters
+## Parameters
 
-* **key**: Name of sketch.
-
-## Return
-
-[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) with information of the filter.
+* **key**: the name of the sketch.
 
 ## Examples
 
@@ -52,3 +48,23 @@ TOPK.INFO topk
 7) decay
 8) "0.92500000000000004"
 ```
+
+## Return information
+
+{{< multitabs id=“topk-info-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) and [integer]({{< relref "/develop/reference/protocol-spec#integers" >}}) pairs. For decay, a [simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) is used to represent the floating point value.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, or key of the incorrect type.
+
+-tab-sep-
+
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [simple string]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) and [integer]({{< relref "/develop/reference/protocol-spec#integers" >}}) pairs. For decay, a [double reply]({{< relref "/develop/reference/protocol-spec#doubles" >}}) is used to represent the floating point value.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: incorrect number of arguments, non-existant key, or key of the incorrect type.
+
+{{< /multitabs >}}

content/commands/topk.list.md

@@ -21,34 +21,24 @@ categories:
 - kubernetes
 - clients
 complexity: O(k*log(k)) where k is the value of top-k
-description: Return full list of items in Top K list
+description: Return the full list of items in the Top-K sketch
 group: topk
 hidden: false
 linkTitle: TOPK.LIST
 module: Bloom
 since: 2.0.0
 stack_path: docs/data-types/probabilistic
-summary: Return full list of items in Top K list
+summary: Return the full list of items in the Top-K sketch
 syntax_fmt: TOPK.LIST key [WITHCOUNT]
 syntax_str: '[WITHCOUNT]'
 title: TOPK.LIST
 ---
-Return full list of items in Top K list.
+Return the full list of items in Top-K sketch.
 
-### Parameters
+## Parameters
 
-* **key**: Name of sketch where item is counted.
-* **WITHCOUNT**: Count of each element is returned.  
-
-## Return
-
-k (or less) items in Top K list.
-
-The list is sorted by decreased count estimation.
-
-[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) - the names of items in the TopK list.
-If `WITHCOUNT` is requested, [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}) and 
-[Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}) pairs of the names of items in the TopK list and their count.
+* **key**: the name of the sketch.
+* **WITHCOUNT**: the count of each element is also returned.
 
 ## Examples
 
@@ -68,3 +58,28 @@ TOPK.LIST topk WITHCOUNT
 5) bar
 6) (integer) 2
 ```
+
+
+## Return information
+
+k (or less) items in the given Top-k sketch. The list is sorted by decreased count estimation.
+
+{{< multitabs id=“topk-info-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the names of items in the given sketch. If `WITHCOUNT` is requested, an [array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) and 
+[integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}) pairs, representing the names of the items in the sketch together with their counts.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: invalid arguments, non-existant key, or key of the incorrect type.
+
+-tab-sep-
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the names of items in the given sketch. If `WITHCOUNT` is requested, an [array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [bulk string reply]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) and 
+[integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}) pairs, representing the names of the items in the sketch together with their counts.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: invalid arguments, non-existant key, or key of the incorrect type.
+
+{{< /multitabs >}}

content/commands/topk.query.md

@@ -32,22 +32,35 @@ syntax_fmt: TOPK.QUERY key item [item ...]
 syntax_str: item [item ...]
 title: TOPK.QUERY
 ---
-Checks whether an item is one of Top-K items.
-Multiple items can be checked at once.
+Checks whether one or more items are one of the Top-K items.
 
-### Parameters
+## Parameters
 
-* **key**: Name of sketch where item is queried.
-* **item**: Item/s to be queried.
+* **key**: the name of the sketch.
+* **item**: the items to be queried.
 
-## Return
-
-[Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}) - "1" if item is in Top-K, otherwise "0".
-
-## Examples
+## Example
 
 ```
 redis> TOPK.QUERY topk 42 nonexist
 1) (integer) 1
 2) (integer) 0
-```
+```
+
+## Return information
+
+{{< multitabs id=“topk-query-return-info" 
+    tab1="RESP2" 
+    tab2="RESP3" >}}
+
+One of the following:
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [integer replies]({{< relref "/develop/reference/protocol-spec#integers" >}}): `1` if an item is in the Top-K or `0` otherwise.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: non-existant key or key of the incorrect type.
+
+-tab-sep-
+
+* [Array]({{< relref "/develop/reference/protocol-spec#arrays" >}}) of [boolean replies]({{< relref "/develop/reference/protocol-spec#booleans" >}}): `true` if an item is in the Top-K or `false` otherwise.
+* [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}) in these cases: non-existant key or key of the incorrect type.
+
+{{< /multitabs >}}