Review Caching infrastructure documentation

Closes gh-33288

framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc

@@ -524,7 +524,7 @@ To enable caching annotations add the annotation `@EnableCaching` to one of your
 ----
 	@Configuration
 	@EnableCaching
-	public class AppConfig {
+	class AppConfig {
 
 		@Bean
 		CacheManager cacheManager() {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -29,8 +29,8 @@ import org.springframework.lang.Nullable;
  * cache management.
  *
  * <p>See @{@link EnableCaching} for general examples and context; see
- * {@link #cacheManager()}, {@link #cacheResolver()} and {@link #keyGenerator()}
+ * {@link #cacheManager()}, {@link #cacheResolver()}, {@link #keyGenerator()}, and
- * for detailed instructions.
+ * {@link #errorHandler()} for detailed instructions.
  *
  * @author Chris Beams
  * @author Stephane Nicoll
@@ -46,14 +46,15 @@ public interface CachingConfigurer {
 	 * management of the cache resolution, consider setting the
 	 * {@link CacheResolver} directly.
 	 * <p>Implementations must explicitly declare
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
+	 * {@link org.springframework.context.annotation.Bean @Bean} so that
+	 * the cache manager participates in the lifecycle of the context, e.g.
 	 * <pre class="code">
 	 * &#064;Configuration
 	 * &#064;EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
+	 * class AppConfig implements CachingConfigurer {
 	 *     &#064;Bean // important!
 	 *     &#064;Override
-	 *     public CacheManager cacheManager() {
+	 *     CacheManager cacheManager() {
 	 *         // configure and return CacheManager instance
 	 *     }
 	 *     // ...
@@ -70,17 +71,18 @@ public interface CachingConfigurer {
 	 * Return the {@link CacheResolver} bean to use to resolve regular caches for
 	 * annotation-driven cache management. This is an alternative and more powerful
 	 * option of specifying the {@link CacheManager} to use.
-	 * <p>If both a {@link #cacheManager()} and {@code #cacheResolver()} are set,
+	 * <p>If both a {@link #cacheManager()} and {@code cacheResolver()} are set,
 	 * the cache manager is ignored.
 	 * <p>Implementations must explicitly declare
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
+	 * {@link org.springframework.context.annotation.Bean @Bean} so that
+	 * the cache resolver participates in the lifecycle of the context, e.g.
 	 * <pre class="code">
 	 * &#064;Configuration
 	 * &#064;EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
+	 * class AppConfig implements CachingConfigurer {
 	 *     &#064;Bean // important!
 	 *     &#064;Override
-	 *     public CacheResolver cacheResolver() {
+	 *     CacheResolver cacheResolver() {
 	 *         // configure and return CacheResolver instance
 	 *     }
 	 *     // ...
@@ -95,20 +97,8 @@ public interface CachingConfigurer {
 
 	/**
 	 * Return the key generator bean to use for annotation-driven cache management.
-	 * Implementations must explicitly declare
+	 * <p>By default, {@link org.springframework.cache.interceptor.SimpleKeyGenerator}
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
+	 * is used.
-	 * <pre class="code">
-	 * &#064;Configuration
-	 * &#064;EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
-	 *     &#064;Bean // important!
-	 *     &#064;Override
-	 *     public KeyGenerator keyGenerator() {
-	 *         // configure and return KeyGenerator instance
-	 *     }
-	 *     // ...
-	 * }
-	 * </pre>
 	 * See @{@link EnableCaching} for more complete examples.
 	 */
 	@Nullable
@@ -118,22 +108,8 @@ public interface CachingConfigurer {
 
 	/**
 	 * Return the {@link CacheErrorHandler} to use to handle cache-related errors.
-	 * <p>By default,{@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
+	 * <p>By default, {@link org.springframework.cache.interceptor.SimpleCacheErrorHandler}
-	 * is used and simply throws the exception back at the client.
+	 * is used, which throws the exception back at the client.
-	 * <p>Implementations must explicitly declare
-	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
-	 * <pre class="code">
-	 * &#064;Configuration
-	 * &#064;EnableCaching
-	 * public class AppConfig implements CachingConfigurer {
-	 *     &#064;Bean // important!
-	 *     &#064;Override
-	 *     public CacheErrorHandler errorHandler() {
-	 *         // configure and return CacheErrorHandler instance
-	 *     }
-	 *     // ...
-	 * }
-	 * </pre>
 	 * See @{@link EnableCaching} for more complete examples.
 	 */
 	@Nullable

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -35,16 +35,16 @@ import org.springframework.core.Ordered;
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableCaching
- * public class AppConfig {
+ * class AppConfig {
  *
  *     &#064;Bean
- *     public MyService myService() {
+ *     MyService myService() {
  *         // configure and return a class having &#064;Cacheable methods
  *         return new MyService();
  *     }
  *
  *     &#064;Bean
- *     public CacheManager cacheManager() {
+ *     CacheManager cacheManager() {
  *         // configure and return an implementation of Spring's CacheManager SPI
  *         SimpleCacheManager cacheManager = new SimpleCacheManager();
  *         cacheManager.setCaches(Set.of(new ConcurrentMapCache("default")));
@@ -103,26 +103,25 @@ import org.springframework.core.Ordered;
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableCaching
- * public class AppConfig implements CachingConfigurer {
+ * class AppConfig implements CachingConfigurer {
  *
  *     &#064;Bean
- *     public MyService myService() {
+ *     MyService myService() {
  *         // configure and return a class having &#064;Cacheable methods
  *         return new MyService();
  *     }
  *
  *     &#064;Bean
  *     &#064;Override
- *     public CacheManager cacheManager() {
+ *     CacheManager cacheManager() {
  *         // configure and return an implementation of Spring's CacheManager SPI
  *         SimpleCacheManager cacheManager = new SimpleCacheManager();
  *         cacheManager.setCaches(Set.of(new ConcurrentMapCache("default")));
  *         return cacheManager;
  *     }
  *
- *     &#064;Bean
  *     &#064;Override
- *     public KeyGenerator keyGenerator() {
+ *     KeyGenerator keyGenerator() {
  *         // configure and return an implementation of Spring's KeyGenerator SPI
  *         return new MyKeyGenerator();
  *     }
@@ -137,9 +136,8 @@ import org.springframework.core.Ordered;
  * org.springframework.cache.interceptor.KeyGenerator KeyGenerator} SPI. Normally,
  * {@code @EnableCaching} will configure Spring's
  * {@link org.springframework.cache.interceptor.SimpleKeyGenerator SimpleKeyGenerator}
- * for this purpose, but when implementing {@code CachingConfigurer}, a key generator
+ * for this purpose, but when implementing {@code CachingConfigurer}, a custom key
- * must be provided explicitly. Return {@code null} or {@code new SimpleKeyGenerator()}
+ * generator can be specified.
- * from this method if no customization is necessary.
  *
  * <p>{@link CachingConfigurer} offers additional customization options:
  * see the {@link CachingConfigurer} javadoc for further details.