From db15681633f302bf076ed9d7b191652ae5dcfe27 Mon Sep 17 00:00:00 2001
From: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
Date: Mon, 16 Jun 2025 10:53:36 +0200
Subject: [PATCH] Update duration expression docs

Signed-off-by: Julien Pivotto <291750+roidelapluie@users.noreply.github.com>
---
 docs/feature_flags.md | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/docs/feature_flags.md b/docs/feature_flags.md
index ff6883e033..08981ee931 100644
--- a/docs/feature_flags.md
+++ b/docs/feature_flags.md
@@ -185,17 +185,25 @@ state is mutex guarded. Cumulative-only OTLP requests are not affected.
 
 `--enable-feature=promql-duration-expr`
 
-With this flag, arithmetic expressions can be used in time durations in range queries and offset durations. For example:
+With this flag, arithmetic expressions can be used in time durations in range queries and offset durations.
 
 In range queries:
-    rate(http_requests_total[5m * 2])  # 10 minute range
-    rate(http_requests_total[(5+2) * 1m])  # 7 minute range
+```
+rate(http_requests_total[5m * 2])  # 10 minute range
+rate(http_requests_total[(5+2) * 1m])  # 7 minute range
+```
 
 In offset durations:
-    http_requests_total offset (1h / 2)  # 30 minute offset
-    http_requests_total offset ((2 ^ 3) * 1m)  # 8 minute offset
+```
+http_requests_total offset (1h / 2)  # 30 minute offset
+http_requests_total offset ((2 ^ 3) * 1m)  # 8 minute offset
+```
 
-Note: Duration expressions are not supported in the @ timestamp operator.
+When using offset with duration expressions, you must wrap the expression in
+parentheses. Without parentheses, only the first duration value will be used in
+the offset calculation.
+
+**Note**: Duration expressions are not supported in the @ timestamp operator.
 
 The following operators are supported: