docs: the retry/aretry decorator needs parentheses (@aretry())

Signed-off-by: disqualifier <dev@disqualifier.me>

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

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)