Merge pull request #28183 from luvarqpp

* pr/28183:
  Polish "Improve documentation of Cacheable"
  Improve documentation of Cacheable

Closes gh-28183

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -111,7 +111,8 @@
 
 	/**
 	 * Spring Expression Language (SpEL) expression used for making the cache
-	 * eviction operation conditional.
+	 * eviction operation conditional. Evict that cache if the condition evaluates
+	 * to {@code true}.
 	 * <p>Default is {@code ""}, meaning the cache eviction is always performed.
 	 * <p>The SpEL expression evaluates against a dedicated context that provides the
 	 * following meta-data:

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -118,7 +118,8 @@
 
 	/**
 	 * Spring Expression Language (SpEL) expression used for making the cache
-	 * put operation conditional.
+	 * put operation conditional. Update the cache if the condition evaluates to
+	 * {@code true}.
 	 * <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.
@@ -142,6 +143,7 @@
 
 	/**
 	 * Spring Expression Language (SpEL) expression used to veto the cache put operation.
+	 * Veto updating the cache if the condition evaluates to {@code true}.
 	 * <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:

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -123,7 +123,8 @@
 
 	/**
 	 * Spring Expression Language (SpEL) expression used for making the method
-	 * caching conditional.
+	 * caching conditional. Cache the result if the condition evaluates to
+	 * {@code true}.
 	 * <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:
@@ -142,6 +143,7 @@
 
 	/**
 	 * Spring Expression Language (SpEL) expression used to veto method caching.
+	 * Veto caching the result if the condition evaluates to {@code true}.
 	 * <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.