Clarify behaviour of condition attribute of CachePut

Closes gh-26186

Author: snicoll

spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,7 +31,8 @@
  *
  * <p>In contrast to the {@link Cacheable @Cacheable} annotation, this annotation
  * does not cause the advised method to be skipped. Rather, it always causes the
- * method to be invoked and its result to be stored in the associated cache. Note
+ * method to be invoked and its result to be stored in the associated cache if the
+ * {@link #condition()} and {@link #unless()} expressions match accordingly. Note
  * that Java8's {@code Optional} return types are automatically handled and its
  * content is stored in the cache if present.
  *
@@ -118,10 +119,15 @@
 	/**
 	 * Spring Expression Language (SpEL) expression used for making the cache
 	 * put operation conditional.
+	 * <p>This expression is evaluated after the method has been called due to the
+	 * nature of the put operation and can therefore refer to the {@code result}.
 	 * <p>Default is {@code ""}, meaning the method result is always cached.
 	 * <p>The SpEL expression evaluates against a dedicated context that provides the
 	 * following meta-data:
 	 * <ul>
+	 * <li>{@code #result} for a reference to the result of the method invocation. For
+	 * supported wrappers such as {@code Optional}, {@code #result} refers to the actual
+	 * object, not the wrapper</li>
 	 * <li>{@code #root.method}, {@code #root.target}, and {@code #root.caches} for
 	 * references to the {@link java.lang.reflect.Method method}, target object, and
 	 * affected cache(s) respectively.</li>
@@ -136,8 +142,6 @@
 
 	/**
 	 * Spring Expression Language (SpEL) expression used to veto the cache put operation.
-	 * <p>Unlike {@link #condition}, this expression is evaluated after the method
-	 * has been called and can therefore refer to the {@code result}.
 	 * <p>Default is {@code ""}, meaning that caching is never vetoed.
 	 * <p>The SpEL expression evaluates against a dedicated context that provides the
 	 * following meta-data: