Apply suggestions from code review

dwdougherty · dwdougherty · commit 0ad2bfddb254 · 2025-07-02T08:42:33.000-07:00
diff --git a/content/commands/xackdel.md b/content/commands/xackdel.md
@@ -52,8 +52,8 @@ categories:
 command_flags:
 - write
 - fast
-complexity: O(1) for each message ID processed.
-description: Acknowledges and deletes one or multiple messages for a stream consumer
+complexity: O(1) for each entry ID processed.
+description: Acknowledges and conditionally deletes one or multiple entries for a stream consumer
   group.
 group: stream
 hidden: false
@@ -73,15 +73,15 @@ key_specs:
   update: true
 linkTitle: XACKDEL
 since: 8.2.0
-summary: Acknowledges and deletes one or multiple messages for a stream consumer group.
+summary: Acknowledges and conditionally deletes one or multiple entries for a stream consumer group.
 syntax_fmt: "XACKDEL key group [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]"
 syntax_str: "group [KEEPREF | DELREF | ACKED] IDS\_numids id [id ...]"
 title: XACKDEL
 ---
 
-Acknowledges and deletes one or multiple messages for a stream consumer group at the specified `key`.
+Acknowledges and conditionally deletes one or multiple entries (messages) for a stream consumer group at the specified `key`.
 
-`XACKDEL` combines the functionality of [`XACK`]({{< relref "/commands/xack" >}}) and [`XDEL`]({{< relref "/commands/xdel" >}}) in Redis Streams. It acknowledges the specified message IDs in the given consumer group and simultaneously attempts to delete the corresponding entries from the stream.
+`XACKDEL` combines the functionality of [`XACK`]({{< relref "/commands/xack" >}}) and [`XDEL`]({{< relref "/commands/xdel" >}}) in Redis Streams. It acknowledges the specified entry IDs in the given consumer group and simultaneously attempts to delete the corresponding entries from the stream.
 
 ## Required arguments
 
@@ -110,14 +110,18 @@ The IDS block specifying which entries to acknowledge and delete:
 <details open>
 <summary><code>KEEPREF | DELREF | ACKED</code></summary>
 
-Specifies how to handle consumer group references when acknowledging and deleting entries. Available since Redis 8.2.0. If no option is specified, `KEEPREF` is used by default:
+Specifies how to handle consumer group references when acknowledging and deleting entries. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default:
 
-- `KEEPREF` (default): Acknowledges the messages in the specified consumer group and deletes the entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List).
-- `DELREF`: Acknowledges the messages in the specified consumer group, deletes the entries from the stream, and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the messages.
-- `ACKED`: Acknowledges the messages in the specified consumer group and only deletes entries that were read and acknowledged by all consumer groups.
+- `KEEPREF` (default): Acknowledges the entries in the specified consumer group and deletes the entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List).
+- `DELREF`: Acknowledges the entries in the specified consumer group, deletes the entries from the stream, and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the entries. If an entry ID is not in the stream, but there are dangling references, `XACKDEL` with `DELREF` would still remove all those references.
+- `ACKED`: Acknowledges the entries in the specified consumer group and only deletes entries that were read and acknowledged by all consumer groups.
 </details>
 
-This command is particularly useful when you want to both acknowledge message processing and clean up the stream in a single atomic operation, providing fine-grained control over how consumer group references are handled.
+This command is particularly useful when you want to both acknowledge entry processing and clean up the stream in a single atomic operation, providing fine-grained control over how entry references are handled.
+
+{{< note >}}
+When using multiple consumer groups, users are encouraged to use `XACKDEL` with the `ACKED` option instead of `XACK` and `XDEL`, simplifying the application logic.
+{{< /note >}}
 
 ## Examples
 
@@ -138,16 +142,22 @@ XRANGE mystream - +
     tab1="RESP2"
     tab2="RESP3" >}}
 
-[Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
-* [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was acknowledged and deleted from the stream.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist.
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): For each ID:
+    * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 1 if the entry was acknowledged and deleted from the stream.
+    * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): -1 if no such ID exists in the provided stream key.
+    * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).
 
 -tab-sep-
 
-[Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
-* [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was acknowledged and deleted from the stream.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist.
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): For each ID:
+    * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 1 if the entry was acknowledged and deleted from the stream.
+    * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): -1 if no such ID exists in the provided stream key.
+    * [Integer reply]({{< relref "/develop/reference/protocol-spec#integers" >}}): 2 if the entry was acknowledged but not deleted, as there are still dangling references (ACKED option).
 
 {{< /multitabs >}}
diff --git a/content/commands/xadd.md b/content/commands/xadd.md
@@ -175,7 +175,7 @@ Prevents the creation of a new stream if the key does not exist. Available since
 <details open>
 <summary><code>KEEPREF | DELREF | ACKED</code></summary>
 
-Specifies how to handle consumer group references when trimming. Available since Redis 8.2.0. If no option is specified, `KEEPREF` is used by default. Unlike the `XDELEX` and `XACKDEL` commands where one of these options is required, here they are optional to maintain backward compatibility:
+Specifies how to handle consumer group references when trimming. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default. Unlike the `XDELEX` and `XACKDEL` commands where one of these options is required, here they are optional to maintain backward compatibility:
 
 - `KEEPREF` (default): When trimming, removes entries from the stream according to the specified strategy (`MAXLEN` or `MINID`), regardless of whether they are referenced by any consumer groups, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List).
 - `DELREF`: When trimming, removes entries from the stream according to the specified strategy and also removes all references to these entries from all consumer groups' PEL.
diff --git a/content/commands/xdelex.md b/content/commands/xdelex.md
@@ -102,10 +102,10 @@ Note: The IDS block can be at any position in the command, same as other command
 <details open>
 <summary><code>KEEPREF | DELREF | ACKED</code></summary>
 
-Specifies how to handle consumer group references when deleting entries. Available since Redis 8.2.0. If no option is specified, `KEEPREF` is used by default:
+Specifies how to handle consumer group references when deleting entries. Available since Redis 8.2. If no option is specified, `KEEPREF` is used by default:
 
 - `KEEPREF` (default): Deletes the specified entries from the stream, but preserves existing references to these entries in all consumer groups' PEL (Pending Entries List). This behavior is similar to [`XDEL`]({{< relref "/commands/xdel" >}}).
-- `DELREF`: Deletes the specified entries from the stream and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the messages.
+- `DELREF`: Deletes the specified entries from the stream and also removes all references to these entries from all consumer groups' pending entry lists, effectively cleaning up all traces of the messages. If an entry ID is not in the stream, but there are dangling references, `XDELEX` with `DELREF` would still remove all those references.
 - `ACKED`: Only deletes entries that were read and acknowledged by all consumer groups.
 </details>
 
@@ -128,16 +128,22 @@ XRANGE mystream - +
     tab1="RESP2"
     tab2="RESP3" >}}
 
-[Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
-* [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was deleted from the stream.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was not deleted, but there are still dangling references (ACKED option).
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist.
+* [Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
+    * [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
+    * [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was deleted from the stream.
+    * [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was not deleted, but there are still dangling references (ACKED option).
 
 -tab-sep-
 
-[Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
-* [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was deleted from the stream.
-* [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was not deleted, but there are still dangling references (ACKED option).
+One of the following:
+
+* [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): -1 for each requested ID when the given key does not exist.
+* [Array reply](../../develop/reference/protocol-spec#arrays): For each ID:
+    * [Integer reply](../../develop/reference/protocol-spec#integers): -1 if no such ID exists in the provided stream key.
+    * [Integer reply](../../develop/reference/protocol-spec#integers): 1 if the entry was deleted from the stream.
+    * [Integer reply](../../develop/reference/protocol-spec#integers): 2 if the entry was not deleted, but there are still dangling references (ACKED option).
 
 {{< /multitabs >}}
diff --git a/content/develop/data-types/streams.md b/content/develop/data-types/streams.md
@@ -9,9 +9,7 @@ categories:
 - oss
 - kubernetes
 - clients
-description: 'Introduction to Redis streams
-
-  '
+description: Introduction to Redis streams
 linkTitle: Streams
 title: Redis Streams
 weight: 60
@@ -28,20 +26,19 @@ Examples of Redis stream use cases include:
 Redis generates a unique ID for each stream entry.
 You can use these IDs to retrieve their associated entries later or to read and process all subsequent entries in the stream. Note that because these IDs are related to time, the ones shown here may vary and will be different from the IDs you see in your own Redis instance.
 
-Redis streams support several trimming strategies (to prevent streams from growing unbounded) and more than one consumption strategy (see [`XREAD`]({{< relref "/commands/xread" >}}), [`XREADGROUP`]({{< relref "/commands/xreadgroup" >}}), and [`XRANGE`]({{< relref "/commands/xrange" >}})). Starting with Redis 8.2, enhanced commands provide fine-grained control over how stream operations interact with multiple consumer groups, simplifying the coordination of message processing across different applications.
+Redis streams support several trimming strategies (to prevent streams from growing unbounded) and more than one consumption strategy (see [`XREAD`]({{< relref "/commands/xread" >}}), [`XREADGROUP`]({{< relref "/commands/xreadgroup" >}}), and [`XRANGE`]({{< relref "/commands/xrange" >}})). Starting with Redis 8.2, the `XACKDEL`, `XDELEX`, `XADD`, and `XTRIM` commands provide fine-grained control over how stream operations interact with multiple consumer groups, simplifying the coordination of message processing across different applications.
 
 ## Basic commands
+
 * [`XADD`]({{< relref "/commands/xadd" >}}) adds a new entry to a stream.
 * [`XREAD`]({{< relref "/commands/xread" >}}) reads one or more entries, starting at a given position and moving forward in time.
 * [`XRANGE`]({{< relref "/commands/xrange" >}}) returns a range of entries between two supplied entry IDs.
 * [`XLEN`]({{< relref "/commands/xlen" >}}) returns the length of a stream.
 * [`XDEL`]({{< relref "/commands/xdel" >}}) removes entries from a stream.
-* [`XDELEX`]({{< relref "/commands/xdelex" >}}) removes entries from a stream with enhanced control over consumer group references.
 * [`XTRIM`]({{< relref "/commands/xtrim" >}}) trims a stream by removing older entries.
 
 See the [complete list of stream commands]({{< relref "/commands/" >}}?group=stream).
 
-
 ## Examples
 
 * When our racers pass a checkpoint, we add a stream entry for each racer that includes the racer's name, speed, position, and location ID:
