From fc9d1760befd30570f57b8cc63b5be5d84fb482a Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <jhoeller@pivotal.io>
Date: Mon, 17 Dec 2018 14:24:21 +0100
Subject: [PATCH] Revised c-namespace example

Issue: SPR-17601
---
 src/docs/asciidoc/core/core-beans.adoc | 42 ++++++++++++++------------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc
index 13494504f56..01335e0e030 100644
--- a/src/docs/asciidoc/core/core-beans.adoc
+++ b/src/docs/asciidoc/core/core-beans.adoc
@@ -927,14 +927,14 @@ element.
 [subs="verbatim,quotes"]
 ----
 	<beans>
-		<bean id="thingOne" class="x.y.ThingOne">
-			<constructor-arg ref="thingTwo"/>
-			<constructor-arg ref="thingThree"/>
+		<bean id="beanOne" class="x.y.ThingOne">
+			<constructor-arg ref="beanTwo"/>
+			<constructor-arg ref="beanThree"/>
 		</bean>
 
-		<bean id="thingTwo" class="x.y.ThingTwo"/>
+		<bean id="beanTwo" class="x.y.ThingTwo"/>
 
-		<bean id="thingThree" class="x.y.ThingThree"/>
+		<bean id="beanThree" class="x.y.ThingThree"/>
 	</beans>
 ----
 ====
@@ -1937,27 +1937,28 @@ The following example uses the `c:` namespace to do the same thing as the from
 		xsi:schemaLocation="http://www.springframework.org/schema/beans
 			http://www.springframework.org/schema/beans/spring-beans.xsd">
 
-		<bean id="thingOne" class="x.y.ThingTwo"/>
-		<bean id="thingTwo" class="x.y.ThingThree"/>
+		<bean id="beanTwo" class="x.y.ThingTwo"/>
+		<bean id="beanThree" class="x.y.ThingThree"/>
 
-		<!-- traditional declaration -->
-		<bean id="thingOne" class="x.y.ThingOne">
-			<constructor-arg ref="thingTwo"/>
-			<constructor-arg ref="thingThree"/>
-			<constructor-arg value="something@somewhere.com"/>
+		<!-- traditional declaration with optional argument names -->
+		<bean id="beanOne" class="x.y.ThingOne">
+			<constructor-arg name="thingTwo" ref="beanTwo"/>
+			<constructor-arg name="thingThree" ref="beanThree"/>
+			<constructor-arg name="email" value="something@somewhere.com"/>
 		</bean>
 
-		<!-- c-namespace declaration -->
-		<bean id="thingOne" class="x.y.ThingOne" c:thingTwo-ref="thingTwo" c:thingThree-ref="thingThree" c:email="something@somewhere.com"/>
+		<!-- c-namespace declaration with argument names -->
+		<bean id="beanOne" class="x.y.ThingOne" c:thingTwo-ref="beanTwo"
+			c:thingThree-ref="beanThree" c:email="something@somewhere.com"/>
 
 	</beans>
 ----
 ====
 
-The `c:` namespace uses the same conventions as the `p:` one (a trailing `-ref` for bean
-references) for setting the constructor arguments by their names. Similarly, it
-needs to be declared even though it is not defined in an XSD schema (it exists
-inside the Spring core).
+The `c:` namespace uses the same conventions as the `p:` one (a trailing `-ref` for
+bean references) for setting the constructor arguments by their names. Similarly,
+it needs to be declared in the XML file even though it is not defined in an XSD schema
+(it exists inside the Spring core).
 
 For the rare cases where the constructor argument names are not available (usually if
 the bytecode was compiled without debugging information), you can use fallback to the
@@ -1968,12 +1969,15 @@ argument indexes, as follows:
 [subs="verbatim,quotes"]
 ----
 	<!-- c-namespace index declaration -->
-	<bean id="thingOne" class="x.y.ThingOne" c:_0-ref="thingTwo" c:_1-ref="thingThree"/>
+	<bean id="beanOne" class="x.y.ThingOne" c:_0-ref="beanTwo" c:_1-ref="beanThree"
+		c:_2="something@somewhere.com"/>
 ----
 ====
 
 NOTE: Due to the XML grammar, the index notation requires the presence of the leading `_`,
 as XML attribute names cannot start with a number (even though some IDEs allow it).
+A corresponding index notation is also available for `<constructor-arg>` elements but
+not commonly used since the plain order of declaration is usually sufficient there.
 
 In practice, the constructor resolution
 <<beans-factory-ctor-arguments-resolution,mechanism>> is quite efficient in matching