From 39a28d07f21350e491512998f055db61458a0b61 Mon Sep 17 00:00:00 2001
From: disqualifier <dev@disqualifier.me>
Date: Fri, 16 Oct 2026 04:40:36 -0400
Subject: [PATCH] docs: the retry/aretry decorator needs parentheses
 (@aretry())

Signed-off-by: disqualifier <dev@disqualifier.me>
---
 README.md            | 5 +++++
 src/commons/retry.py | 8 ++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 050ac19..55fecff 100644
--- a/README.md
+++ b/README.md
@@ -202,6 +202,11 @@ async def pull():
     ...
 ```
 
+The decorator always needs parentheses, even with no kwargs: `@retry()` / `@aretry()`. A
+bare `@retry` / `@aretry` is the call form applied to the function: `@retry` runs it once
+at import time and replaces it with its return value, and `@aretry` replaces it with a
+coroutine that is never awaited.
+
 Knobs: `attempts` (total tries), `backoff` / `factor` / `max_backoff` (delay is
 `min(backoff * factor**n, max_backoff)`), `jitter` (full jitter, on by default),
 `on=` (tuple of retryable exception types), and `give_up=lambda exc: ...` to stop early
diff --git a/src/commons/retry.py b/src/commons/retry.py
index 8da42b9..3b55bed 100644
--- a/src/commons/retry.py
+++ b/src/commons/retry.py
@@ -56,7 +56,9 @@ def retry(
 ):
     """retry a sync callable with exponential backoff; call form (`retry(fn, ...)`) or decorator
 
-    `attempts` is floored at 1 so the callable always runs at least once.
+    the decorator needs parentheses - `@retry()` / `@retry(attempts=5)`. a bare `@retry`
+    is the call form: it runs the function once at import time and replaces it with the
+    result. `attempts` is floored at 1 so the callable always runs at least once.
     """
     types = _as_types(on)
     attempts = max(1, attempts)
@@ -106,7 +108,9 @@ def aretry(
 ):
     """async twin of `retry`; call form (`await aretry(coro_fn, ...)`) or decorator, same semantics
 
-    `attempts` is floored at 1 so the callable always runs at least once.
+    the decorator needs parentheses - `@aretry()` / `@aretry(attempts=5)`. a bare `@aretry`
+    is the call form: it replaces the function with a never-awaited coroutine. `attempts`
+    is floored at 1 so the callable always runs at least once.
     """
     types = _as_types(on)
     attempts = max(1, attempts)