From 2aa36fea64d580d0e2e531ac96e6ed31660bd412 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Fri, 18 Sep 2026 16:48:27 +0200
Subject: [PATCH] Polish contribution

See gh-37005
---
 .../modules/ROOT/pages/core/resilience.adoc          | 12 ++++++++++++
 .../ROOT/pages/integration/cache/annotations.adoc    | 11 +++++++++++
 2 files changed, 23 insertions(+)

diff --git a/framework-docs/modules/ROOT/pages/core/resilience.adoc b/framework-docs/modules/ROOT/pages/core/resilience.adoc
index d8010416f46..11434ae5106 100644
--- a/framework-docs/modules/ROOT/pages/core/resilience.adoc
+++ b/framework-docs/modules/ROOT/pages/core/resilience.adoc
@@ -155,6 +155,9 @@ exception. The retry interceptor sees the same, unwrapped exception that the tar
 method threw.
 ====
 
+TIP: See xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`]
+for general details on declarative transaction management.
+
 [[resilience-annotations-retryable-combining-cacheable]]
 ==== With `@Cacheable`
 
@@ -168,6 +171,9 @@ The cache interceptor runs on every attempt. If the cache is populated between a
 (for example, by a concurrent request), subsequent retry attempts will return the cached
 value without invoking the target method. On success, the cache is populated as normal.
 
+The same fixed ordering applies to `@CacheEvict` and `@CachePut`, since they share the
+same underlying cache advisor.
+
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 @Cacheable("items")
@@ -177,6 +183,9 @@ public Item loadItem(String id) {
 }
 ----
 
+TIP: See xref:integration/cache/annotations.adoc#cache-annotations-cacheable[The `@Cacheable` Annotation]
+for general details on declarative caching.
+
 [[resilience-annotations-retryable-combining-async]]
 ==== With `@Async`
 
@@ -206,6 +215,9 @@ All retry attempts, including any configured delay between them, happen on the a
 executor thread.
 ====
 
+TIP: See xref:integration/scheduling.adoc#scheduling-annotation-support-async[The `@Async` annotation]
+for general details on asynchronous method execution.
+
 [[resilience-annotations-retryable-combining-order]]
 ==== Adjusting Advice Order
 
diff --git a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc
index d8b401a7217..eea2a0a7744 100644
--- a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc
+++ b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc
@@ -416,6 +416,11 @@ confirm the exclusion.
 As of 6.1, `@CachePut` takes `CompletableFuture` and reactive return types into account,
 performing the put operation whenever the produced object is available.
 
+TIP: When `@CachePut` is combined with `@Retryable`, the retry advice is applied
+outermost, so each successful retry attempt updates the cache; a failed attempt does
+not. See xref:core/resilience.adoc#resilience-annotations-retryable-combining-cacheable[Combining `@Retryable` with `@Cacheable`]
+for details.
+
 
 [[cache-annotations-evict]]
 == The `@CacheEvict` Annotation
@@ -461,6 +466,12 @@ and, thus, requires a result.
 As of 6.1, `@CacheEvict` takes `CompletableFuture` and reactive return types into account,
 performing an after-invocation evict operation whenever processing has completed.
 
+TIP: When `@CacheEvict` is combined with `@Retryable`, the retry advice is applied
+outermost, so eviction runs again on every retry attempt -- and, with
+`beforeInvocation=true`, before each attempt regardless of its outcome. See
+xref:core/resilience.adoc#resilience-annotations-retryable-combining-cacheable[Combining `@Retryable` with `@Cacheable`]
+for details.
+
 
 [[cache-annotations-caching]]
 == The `@Caching` Annotation