From 2e4e43b5bdd6c548fcb644540e09559fd3433969 Mon Sep 17 00:00:00 2001
From: Sam Brannen <sam@sambrannen.com>
Date: Thu, 31 Aug 2023 13:38:13 +0200
Subject: [PATCH 1/2] Polish org.springframework.core.env.PropertySource

See gh-30195
---
 .../core/env/PropertySource.java              | 21 +++++++++++--------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/spring-core/src/main/java/org/springframework/core/env/PropertySource.java b/spring-core/src/main/java/org/springframework/core/env/PropertySource.java
index f50968d2bba..64ad2c0d928 100644
--- a/spring-core/src/main/java/org/springframework/core/env/PropertySource.java
+++ b/spring-core/src/main/java/org/springframework/core/env/PropertySource.java
@@ -92,6 +92,8 @@ public abstract class PropertySource<T> {
 
 	/**
 	 * Return the name of this {@code PropertySource}.
+	 * <p>See the {@linkplain PropertySource class-level Javadoc} for details
+	 * on property source identity and names.
 	 */
 	public String getName() {
 		return this.name;
@@ -170,21 +172,22 @@ public abstract class PropertySource<T> {
 
 
 	/**
-	 * Return a {@code PropertySource} implementation intended for collection comparison purposes only.
-	 * <p>Primarily for internal use, but given a collection of {@code PropertySource} objects, may be
-	 * used as follows:
+	 * Return a {@code PropertySource} implementation intended for collection
+	 * comparison purposes only.
+	 * <p>Primarily for internal use, but given a collection of {@code PropertySource}
+	 * objects, may be used as follows:
 	 * <pre class="code">
-	 * {@code List<PropertySource<?>> sources = new ArrayList<PropertySource<?>>();
+	 * List&lt;PropertySource&lt;?&gt;&gt; sources = new ArrayList&lt;&gt;();
 	 * sources.add(new MapPropertySource("sourceA", mapA));
 	 * sources.add(new MapPropertySource("sourceB", mapB));
 	 * assert sources.contains(PropertySource.named("sourceA"));
 	 * assert sources.contains(PropertySource.named("sourceB"));
-	 * assert !sources.contains(PropertySource.named("sourceC"));
-	 * }</pre>
-	 * The returned {@code PropertySource} will throw {@code UnsupportedOperationException}
+	 * assert !sources.contains(PropertySource.named("sourceC"));</pre>
+	 * <p>The returned {@code PropertySource} will throw {@code UnsupportedOperationException}
 	 * if any methods other than {@code equals(Object)}, {@code hashCode()}, and {@code toString()}
 	 * are called.
-	 * @param name the name of the comparison {@code PropertySource} to be created and returned.
+	 * @param name the name of the comparison {@code PropertySource} to be created
+	 * and returned
 	 */
 	public static PropertySource<?> named(String name) {
 		return new ComparisonPropertySource(name);
@@ -206,7 +209,7 @@ public abstract class PropertySource<T> {
 	public static class StubPropertySource extends PropertySource<Object> {
 
 		public StubPropertySource(String name) {
-			super(name, new Object());
+			super(name);
 		}
 
 		/**

From c01e1b890139f82287cad7d4a36b022e2e2fcecf Mon Sep 17 00:00:00 2001
From: Sam Brannen <sam@sambrannen.com>
Date: Thu, 31 Aug 2023 13:39:22 +0200
Subject: [PATCH 2/2] Document purpose of the name attribute in @PropertySource

Closes gh-30195
---
 .../context/annotation/PropertySource.java    | 27 +++++++++++++++----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java b/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java
index 2dc039b9403..a112a3c9e43 100644
--- a/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java
+++ b/spring-context/src/main/java/org/springframework/context/annotation/PropertySource.java
@@ -171,11 +171,28 @@ import org.springframework.core.io.support.PropertySourceFactory;
 public @interface PropertySource {
 
 	/**
-	 * Indicate the name of this property source. If omitted, the {@link #factory}
-	 * will generate a name based on the underlying resource (in the case of
-	 * {@link org.springframework.core.io.support.DefaultPropertySourceFactory}:
-	 * derived from the resource description through a corresponding name-less
-	 * {@link org.springframework.core.io.support.ResourcePropertySource} constructor).
+	 * Indicate the unique name of this property source.
+	 * <p>If omitted, the {@link #factory} will generate a name based on the
+	 * underlying resource (in the case of
+	 * {@link org.springframework.core.io.support.DefaultPropertySourceFactory
+	 * DefaultPropertySourceFactory}: derived from the resource description through
+	 * a corresponding name-less
+	 * {@link org.springframework.core.io.support.ResourcePropertySource
+	 * ResourcePropertySource} constructor).
+	 * <p>The name of a {@code PropertySource} serves two general purposes.
+	 * <ul>
+	 * <li>Diagnostics: to determine the source of the properties in logging and
+	 * debugging &mdash; for example, in a Spring Boot application via Spring
+	 * Boot's {@code PropertySourceOrigin}.</li>
+	 * <li>Programmatic interaction with
+	 * {@link org.springframework.core.env.MutablePropertySources MutablePropertySources}:
+	 * the name can be used to retrieve properties from a particular property
+	 * source (or to determine if a particular named property source already exists).
+	 * The name can also be used to add a new property source relative to an existing
+	 * property source (see
+	 * {@link org.springframework.core.env.MutablePropertySources#addBefore addBefore()} and
+	 * {@link org.springframework.core.env.MutablePropertySources#addAfter addAfter()}).</li>
+	 * </ul>
 	 * @see org.springframework.core.env.PropertySource#getName()
 	 * @see org.springframework.core.io.Resource#getDescription()
 	 */