Stronger warning about lookup methods not working with @bean

Issue: SPR-13108

Author: jhoeller

spring-beans/src/main/java/org/springframework/beans/factory/annotation/Lookup.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -38,12 +38,15 @@
  * container to fill them in at runtime. In both cases, the container will generate
  * runtime subclasses of the method's containing class via CGLIB, which is why such
  * lookup methods can only work on beans that the container instantiates through
- * regular constructors (i.e. lookup methods cannot get replaced on beans returned
- * from factory methods where we can't dynamically provide a subclass for them).
+ * regular constructors: i.e. lookup methods cannot get replaced on beans returned
+ * from factory methods where we cannot dynamically provide a subclass for them.
  *
- * <p>Note: When used with component scanning or any other mechanism that filters
- * out abstract beans, provide stub implementations of your lookup methods to be
- * able to declare them as concrete classes.
+ * <p><b>Concrete limitations in typical Spring configuration scenarios:</b>
+ * When used with component scanning or any other mechanism that filters out abstract
+ * beans, provide stub implementations of your lookup methods to be able to declare
+ * them as concrete classes. And please remember that lookup methods won't work on
+ * beans returned from {@code @Bean} methods in configuration classes; you'll have
+ * to resort to {@code @Inject Provider&lt;TargetBean&gt;} or the like instead.
  *
  * @author Juergen Hoeller
  * @since 4.1

src/asciidoc/core-beans.adoc

@@ -2032,15 +2032,17 @@ overrides the method.
 
 [NOTE]
 ====
-For this dynamic subclassing to work, the class that the Spring container will subclass
-cannot be `final`, and the method to be overridden cannot be `final` either. Also,
-testing a class that has an `abstract` method requires you to subclass the class
-yourself and to supply a stub implementation of the `abstract` method. Finally, objects
-that have been the target of method injection cannot be serialized. As of Spring 3.2 it
-is no longer necessary to add CGLIB to your classpath, because CGLIB classes are
-repackaged under org.springframework and distributed within the spring-core JAR. This is
-done both for convenience as well as to avoid potential conflicts with other projects
-that use differing versions of CGLIB.
+* For this dynamic subclassing to work, the class that the Spring bean container will
+  subclass cannot be `final`, and the method to be overridden cannot be `final` either.
+* Unit-testing a class that has an `abstract` method requires you to subclass the class
+  yourself and to supply a stub implementation of the `abstract` method.
+* Concrete methods are also necessary for component scanning which requires concrete
+  classes to pick up.
+* A further key limitation is that lookup methods won't work with factory methods and
+  in particular not with `@Bean` methods in configuration classes, since the container
+  is not in charge of creating the instance in that case and therefore cannot create
+  a runtime-generated subclass on the fly.
+* Finally, objects that have been the target of method injection cannot be serialized.
 ====
 
 Looking at the `CommandManager` class in the previous code snippet, you see that the
@@ -2116,7 +2118,7 @@ these classes for additional information.
 
 [[beans-factory-arbitrary-method-replacement]]
 ==== Arbitrary method replacement
-A less useful form of method injection than lookup method Injection is the ability to
+A less useful form of method injection than lookup method injection is the ability to
 replace arbitrary methods in a managed bean with another method implementation. Users
 may safely skip the rest of this section until the functionality is actually needed.