Improve documentation for literals in SpEL expressions

sbrannen · sbrannen · commit 916539178b2e · 2022-12-16T14:51:48.000+01:00
Closes gh-29701
diff --git a/src/docs/asciidoc/core/core-expressions.adoc b/src/docs/asciidoc/core/core-expressions.adoc
@@ -744,25 +744,42 @@ topics:
 [[expressions-ref-literal]]
 === Literal Expressions
 
-The types of literal expressions supported are strings, numeric values (int, real, hex),
-boolean, and null. Strings are delimited by single quotation marks. To put a single quotation mark itself
-in a string, use two single quotation mark characters.
+SpEL supports the following types of literal expressions.
 
-The following listing shows simple usage of literals. Typically, they are not used
-in isolation like this but, rather, as part of a more complex expression -- for example,
-using a literal on one side of a logical comparison operator.
+- strings
+- numeric values: integer (`int` or `long`), hexadecimal (`int` or `long`), real (`float`
+  or `double`)
+- boolean values: `true` or `false`
+- null
+
+Strings can delimited by single quotation marks (`'`) or double quotation marks (`"`). To
+include a single quotation mark within a string literal enclosed in single quotation
+marks, use two adjacent single quotation mark characters. Similarly, to include a double
+quotation mark within a string literal enclosed in double quotation marks, use two
+adjacent double quotation mark characters.
+
+Numbers support the use of the negative sign, exponential notation, and decimal points.
+By default, real numbers are parsed by using `Double.parseDouble()`.
+
+The following listing shows simple usage of literals. Typically, they are not used in
+isolation like this but, rather, as part of a more complex expression -- for example,
+using a literal on one side of a logical comparison operator or as an argument to a
+method.
 
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
 ----
 	ExpressionParser parser = new SpelExpressionParser();
 
-	// evals to "Hello World"
+	// evaluates to "Hello World"
 	String helloWorld = (String) parser.parseExpression("'Hello World'").getValue();
 
+	// evaluates to "Tony's Pizza"
+	String pizzaParlor = (String) parser.parseExpression("'Tony''s Pizza'").getValue();
+
 	double avogadrosNumber = (Double) parser.parseExpression("6.0221415E+23").getValue();
 
-	// evals to 2147483647
+	// evaluates to 2147483647
 	int maxValue = (Integer) parser.parseExpression("0x7FFFFFFF").getValue();
 
 	boolean trueValue = (Boolean) parser.parseExpression("true").getValue();
@@ -774,22 +791,22 @@ using a literal on one side of a logical comparison operator.
 ----
 	val parser = SpelExpressionParser()
 
-	// evals to "Hello World"
+	// evaluates to "Hello World"
 	val helloWorld = parser.parseExpression("'Hello World'").value as String
 
+	// evaluates to "Tony's Pizza"
+	val pizzaParlor = parser.parseExpression("'Tony''s Pizza'").value as String
+
 	val avogadrosNumber = parser.parseExpression("6.0221415E+23").value as Double
 
-	// evals to 2147483647
+	// evaluates to 2147483647
 	val maxValue = parser.parseExpression("0x7FFFFFFF").value as Int
 
 	val trueValue = parser.parseExpression("true").value as Boolean
 
 	val nullValue = parser.parseExpression("null").value
 ----
 
-Numbers support the use of the negative sign, exponential notation, and decimal points.
-By default, real numbers are parsed by using `Double.parseDouble()`.
-
 
 
 [[expressions-properties-arrays]]
@@ -804,15 +821,15 @@ Pupin's city of birth, we use the following expressions:
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
 ----
-	// evals to 1856
+	// evaluates to 1856
 	int year = (Integer) parser.parseExpression("birthdate.year + 1900").getValue(context);
 
 	String city = (String) parser.parseExpression("placeOfBirth.city").getValue(context);
 ----
 [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
 .Kotlin
 ----
-	// evals to 1856
+	// evaluates to 1856
 	val year = parser.parseExpression("birthdate.year + 1900").getValue(context) as Int
 
 	val city = parser.parseExpression("placeOfBirth.city").getValue(context) as String
