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] 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()
 	 */