From 4f607b59a36f17b768a4f666e4769ce3cafe06b7 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Sat, 10 Aug 2024 16:44:17 +0300
Subject: [PATCH] Improve document for SpEL Bean References

---
 .../language-ref/bean-references.adoc         | 36 +++++++++++--------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc
index 82e68876b1..51f79b2e38 100644
--- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc
+++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/bean-references.adoc
@@ -1,8 +1,8 @@
 [[expressions-bean-references]]
 = Bean References
 
-If the evaluation context has been configured with a bean resolver, you can
-look up beans from an expression by using the `@` symbol. The following example shows how
+If the evaluation context has been configured with a bean resolver, you can look up beans
+from an expression by using the `@` symbol as a prefix. The following example shows how
 to do so:
 
 [tabs]
@@ -15,8 +15,9 @@ Java::
 	StandardEvaluationContext context = new StandardEvaluationContext();
 	context.setBeanResolver(new MyBeanResolver());
 
-	// This will end up calling resolve(context,"something") on MyBeanResolver during evaluation
-	Object bean = parser.parseExpression("@something").getValue(context);
+	// This will end up calling resolve(context, "someBean") on MyBeanResolver
+	// during evaluation.
+	Object bean = parser.parseExpression("@someBean").getValue(context);
 ----
 
 Kotlin::
@@ -27,13 +28,20 @@ Kotlin::
 	val context = StandardEvaluationContext()
 	context.setBeanResolver(MyBeanResolver())
 
-	// This will end up calling resolve(context,"something") on MyBeanResolver during evaluation
-	val bean = parser.parseExpression("@something").getValue(context)
+	// This will end up calling resolve(context, "someBean") on MyBeanResolver
+	// during evaluation.
+	val bean = parser.parseExpression("@someBean").getValue(context)
 ----
 ======
 
-To access a factory bean itself, you should instead prefix the bean name with an `&` symbol.
-The following example shows how to do so:
+[NOTE]
+====
+If a bean name contains a dot (`.`) or other special characters, you must provide the
+name of the bean as a _string literal_ – for example, `@'order.service'`.
+====
+
+To access a factory bean itself, you should instead prefix the bean name with an `&`
+symbol. The following example shows how to do so:
 
 [tabs]
 ======
@@ -45,8 +53,9 @@ Java::
 	StandardEvaluationContext context = new StandardEvaluationContext();
 	context.setBeanResolver(new MyBeanResolver());
 
-	// This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation
-	Object bean = parser.parseExpression("&foo").getValue(context);
+	// This will end up calling resolve(context, "&someFactoryBean") on
+	// MyBeanResolver during evaluation.
+	Object factoryBean = parser.parseExpression("&someFactoryBean").getValue(context);
 ----
 
 Kotlin::
@@ -57,9 +66,8 @@ Kotlin::
 	val context = StandardEvaluationContext()
 	context.setBeanResolver(MyBeanResolver())
 
-	// This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluation
-	val bean = parser.parseExpression("&foo").getValue(context)
+	// This will end up calling resolve(context, "&someFactoryBean") on
+	// MyBeanResolver during evaluation.
+	val factoryBean = parser.parseExpression("&someFactoryBean").getValue(context)
 ----
 ======
-
-