Explicit note about @Profile declarations on overloaded @Bean methods

Also marks @Conditional as @Documented, aligned with other annotations.

Issue: SPR-15266

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -16,6 +16,7 @@
 
 package org.springframework.context.annotation;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -55,8 +56,9 @@ import java.lang.annotation.Target;
  * @since 4.0
  * @see Condition
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
 public @interface Conditional {
 
 	/**

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -57,12 +57,19 @@ import org.springframework.core.env.ConfigurableEnvironment;
  *
  * <p>If a given profile is prefixed with the NOT operator ({@code !}), the annotated
  * component will be registered if the profile is <em>not</em> active &mdash; for example,
- * given {@code @Profile({"p1", "!p2"})}, registration will occur if profile 'p1' is active or
- * if profile 'p2' is <em>not</em> active.
+ * given {@code @Profile({"p1", "!p2"})}, registration will occur if profile 'p1' is active
+ * or if profile 'p2' is <em>not</em> active.
  *
  * <p>If the {@code @Profile} annotation is omitted, registration will occur regardless
  * of which (if any) profiles are active.
  *
+ * <p><b>NOTE:</b> With {@code @Profile} on {@code @Bean} methods, a special scenario may
+ * apply: In the case of overloaded {@code @Bean} methods, all {@code @Profile} declarations
+ * from all applicable factory methods for the same bean will be merged; as a consequence,
+ * they all need to match for the bean to become registered. {@code @Profile} can therefore
+ * not be used to select a particular overloaded method over another; resolution between
+ * overloaded factory methods only follows Spring's constructor resolution algorithm.
+ *
  * <p>When defining Spring beans via XML, the {@code "profile"} attribute of the
  * {@code <beans>} element may be used. See the documentation in the
  * {@code spring-beans} XSD (version 3.1 or greater) for details.
@@ -78,8 +85,8 @@ import org.springframework.core.env.ConfigurableEnvironment;
  * @see Conditional
  * @see org.springframework.test.context.ActiveProfiles
  */
-@Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
 @Documented
 @Conditional(ProfileCondition.class)
 public @interface Profile {

src/docs/asciidoc/core/core-beans.adoc

@@ -7416,6 +7416,9 @@ jdbc.password=
 	}
 ----
 
+
+
+
 [[beans-environment]]
 == Environment abstraction
 
@@ -7437,6 +7440,8 @@ on. The role of the `Environment` object with relation to properties is to provi
 user with a convenient service interface for configuring property sources and resolving
 properties from them.
 
+
+
 [[beans-definition-profiles]]
 === Bean definition profiles
 
@@ -7563,6 +7568,18 @@ of creating a custom _composed annotation_. The following example defines a cust
 	}
 ----
 
+[TIP]
+====
+If a `@Configuration` class is marked with `@Profile`, all of the `@Bean` methods and
+`@Import` annotations associated with that class will be bypassed unless one or more of
+the specified profiles are active. If a `@Component` or `@Configuration` class is marked
+with `@Profile({"p1", "p2"})`, that class will not be registered/processed unless
+profiles 'p1' and/or 'p2' have been activated. If a given profile is prefixed with the
+NOT operator (`!`), the annotated element will be registered if the profile is **not**
+active. For example, given `@Profile({"p1", "!p2"})`, registration will occur if profile
+'p1' is active or if profile 'p2' is not active.
+====
+
 `@Profile` can also be declared at the method level to include only one particular bean
 of a configuration class:
 
@@ -7591,20 +7608,19 @@ of a configuration class:
 	}
 ----
 
-[TIP]
+[NOTE]
 ====
-If a `@Configuration` class is marked with `@Profile`, all of the `@Bean` methods and
-`@Import` annotations associated with that class will be bypassed unless one or more of
-the specified profiles are active. If a `@Component` or `@Configuration` class is marked
-with `@Profile({"p1", "p2"})`, that class will not be registered/processed unless
-profiles 'p1' and/or 'p2' have been activated. If a given profile is prefixed with the
-NOT operator (`!`), the annotated element will be registered if the profile is **not**
-active. For example, given `@Profile({"p1", "!p2"})`, registration will occur if profile
-'p1' is active or if profile 'p2' is not active.
+With `@Profile` on `@Bean` methods, a special scenario may apply: In the case of
+overloaded `@Bean` methods, all `@Profile` declarations from all applicable factory
+methods for the same bean will be merged; as a consequence, they all need to match
+for the bean to become registered. `@Profile` can therefore not be used to select
+a particular overloaded method over another; resolution between overloaded factory
+methods only follows Spring's constructor resolution algorithm.
 ====
 
+
 [[beans-definition-profiles-xml]]
-=== XML bean definition profiles
+==== XML bean definition profiles
 
 The XML counterpart is the `profile` attribute of the `<beans>` element. Our sample
 configuration above can be rewritten in two XML files as follows: