Document registration recommendations for BeanPostProcessor and BeanFactoryPostProcessor

Closes gh-34964

spring-context/src/main/java/org/springframework/context/annotation/Bean.java

@@ -194,6 +194,31 @@ import org.springframework.core.annotation.AliasFor;
  * issued for any non-static {@code @Bean} methods having a return type assignable to
  * {@code BeanFactoryPostProcessor}.
  *
+ * <h3>{@code BeanPostProcessor}-returning {@code @Bean} methods</h3>
+ *
+ * <p>Similarly, special consideration must be taken for {@code @Bean} methods that return Spring
+ * {@link org.springframework.beans.factory.config.BeanPostProcessor BeanPostProcessor}
+ * ({@code BPP}) types. Because {@code BPP} objects must be instantiated early in the container
+ * lifecycle, a non-static {@code @Bean} method that returns a {@code BPP} will cause eager
+ * initialization of its declaring {@code @Configuration} class, which can make other beans in the
+ * {@code @Configuration} class (as well as depencencies of those beans) ineligible for full
+ * post-processing. To avoid these lifecycle issues, mark {@code BPP}-returning {@code @Bean}
+ * methods as {@code static}. For example:
+ *
+ * <pre class="code">
+ * &#064;Bean
+ * public static MyBeanPostProcessor myBeanPostProcessor() {
+ *     return new MyBeanPostProcessor();
+ * }</pre>
+ *
+ * By marking this method as {@code static}, it can be invoked without causing instantiation of its
+ * declaring {@code @Configuration} class. Furthermore, the method should ideally not declare any
+ * dependencies so that the container does not need to instantiate other beans to create the
+ * post-processor, which would make those beans ineligible for post-processing as well. For any such
+ * bean, you should see a WARN-level log message similar to the following: "Bean 'someBean' of type
+ * [org.example.SomeType] is not eligible for getting processed by all BeanPostProcessors (for example:
+ * not eligible for auto-proxying)".
+ *
  * @author Rod Johnson
  * @author Costin Leau
  * @author Chris Beams