DEV: clarify trimming threshold definitions in XTRIM and XADD

content/commands/xadd.md

@@ -116,9 +116,9 @@ linkTitle: XADD
 railroad_diagram: /images/railroad/xadd.svg
 since: 5.0.0
 summary: Appends a new message to a stream. Creates the key if it doesn't exist.
-syntax_fmt: "XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold\n  [LIMIT\_\
+syntax_fmt: "XADD key [NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<MAXLEN | MINID> [= | ~] threshold\n  [LIMIT\_\
   count]] <* | id> field value [field value ...]"
-syntax_str: "[NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold [LIMIT\_count]] <* |\
+syntax_str: "[NOMKSTREAM] [KEEPREF | DELREF | ACKED] [<MAXLEN | MINID> [= | ~] threshold [LIMIT\_count]] <* |\
   \ id> field value [field value ...]"
 title: XADD
 ---
@@ -168,17 +168,42 @@ If no option is specified, `KEEPREF` is used by default. Unlike the `XDELEX` and
 </details>
 
 <details open>
-<summary><code>MAXLEN | MINID [= | ~] threshold [LIMIT count]</code></summary>
+<summary><code>MAXLEN | MINID [= | ~] threshold [LIMIT count]></code></summary>
 
 Trims the stream to maintain a specific size or remove old entries:
-- `MAXLEN`: Limits the stream to a maximum number of entries
-- `MINID`: Removes entries with IDs lower than the specified threshold (available since Redis 6.2.0)
-- `=`: Exact trimming (default)
-- `~`: Approximate trimming (more efficient)
-- `threshold`: The maximum number of entries (for MAXLEN) or minimum ID (for MINID)
-- `LIMIT count`: Limits the number of entries to examine during trimming (available since Redis 6.2.0)
+
+<details open>
+<summary><code>MAXLEN | MINID</code></summary>
+
+The trimming strategy:
+- `MAXLEN`: Evicts entries as long as the stream's length exceeds the specified threshold
+- `MINID`: Evicts entries with IDs lower than the specified threshold (available since Redis 6.2.0)
+</details>
+
+<details open>
+<summary><code>= | ~</code></summary>
+
+The trimming operator:
+- `=`: Exact trimming (default) - trims to the exact threshold
+- `~`: Approximate trimming - more efficient, may leave slightly more entries than the threshold
+</details>
+
+<details open>
+<summary><code>threshold</code></summary>
+
+The trimming threshold:
+- For `MAXLEN`: `threshold` is a non-negative integer specifying the maximum number of entries that may remain in the stream after trimming. Redis enforces this by removing the oldest entries - that is, the entries with the lowest stream IDs - so that only the newest entries are kept.
+- For `MINID`: `threshold` is a stream ID. All entries whose IDs are less than `threshold` are trimmed. All entries with IDs greater than or equal to `threshold` are kept.
+</details>
+
+<details open>
+<summary><code>LIMIT count</code></summary>
+
+Limits the number of entries to examine during trimming. Available since Redis 6.2.0. When not specified, Redis uses a default value of 100 * the number of entries in a macro node. Specifying 0 disables the limiting mechanism entirely.
 </details>
 
+</details>
+
 Each entry consists of a list of field-value pairs.
 Redis stores the field-value pairs in the same order you provide them.
 Commands that read the stream, such as [`XRANGE`]({{< relref "/commands/xrange" >}}) or [`XREAD`]({{< relref "/commands/xread" >}}), return the fields and values in exactly the same order you added them with `XADD`.

content/commands/xtrim.md

@@ -85,8 +85,8 @@ linkTitle: XTRIM
 railroad_diagram: /images/railroad/xtrim.svg
 since: 5.0.0
 summary: Deletes messages from the beginning of a stream.
-syntax_fmt: "XTRIM key <MAXLEN | MINID> [= | ~] threshold [LIMIT\_count]"
-syntax_str: "<MAXLEN | MINID> [= | ~] threshold [LIMIT\_count]"
+syntax_fmt: "XTRIM key <MAXLEN | MINID> [= | ~] threshold [LIMIT\_count] [KEEPREF | DELREF | ACKED]"
+syntax_str: "<MAXLEN | MINID> [= | ~] threshold [LIMIT\_count] [KEEPREF | DELREF | ACKED]"
 title: XTRIM
 ---
 
@@ -111,7 +111,9 @@ The trimming strategy:
 <details open>
 <summary><code>threshold</code></summary>
 
-The trimming threshold. For `MAXLEN`, this is a positive integer representing the maximum number of entries. For `MINID`, this is a stream ID.
+The trimming threshold:
+- For `MAXLEN`: `threshold` is a non-negative integer specifying the maximum number of entries that may remain in the stream after trimming. Redis enforces this by removing the oldest entries - that is, the entries with the lowest stream IDs - so that only the newest entries are kept.
+- For `MINID`: `threshold` is a stream ID. All entries whose IDs are less than `threshold` are trimmed. All entries with IDs greater than or equal to `threshold` are kept.
 </details>
 
 ## Optional arguments
@@ -142,11 +144,6 @@ If no option is specified, `KEEPREF` is used by default. Unlike the `XDELEX` and
 - `ACKED`: When trimming, only removes entries that were read and acknowledged by all consumer groups. Note that if the number of referenced entries is larger than `MAXLEN`, trimming will still stop at the limit.
 </details>
 
-You can trim the stream using one of these strategies:
-
-* `MAXLEN`: Evicts entries as long as the stream's length exceeds the specified `threshold`, where `threshold` is a positive integer.
-* `MINID`: Evicts entries with IDs lower than `threshold`, where `threshold` is a stream ID.
-
 For example, this trims the stream to exactly the latest 1000 items:
 
 ```