From 91258271e41ed7e998d475fb1a807a61c48508f1 Mon Sep 17 00:00:00 2001
From: Marc Wrobel <marc.wrobel@gmail.com>
Date: Tue, 12 Jul 2022 15:57:04 +0200
Subject: [PATCH] Fix and improve Javadoc in spring-expression

Closes gh-28800
---
 .../springframework/expression/ConstructorResolver.java    | 2 +-
 .../java/org/springframework/expression/ParserContext.java | 2 +-
 .../java/org/springframework/expression/spel/CodeFlow.java | 4 ++--
 .../java/org/springframework/expression/spel/SpelNode.java | 2 +-
 .../expression/spel/ast/ConstructorReference.java          | 6 +++---
 .../org/springframework/expression/spel/ast/Elvis.java     | 7 ++++---
 .../expression/spel/ast/OperatorInstanceof.java            | 4 ++--
 .../expression/spel/ast/PropertyOrFieldReference.java      | 2 +-
 .../org/springframework/expression/spel/ast/Ternary.java   | 2 +-
 .../spel/standard/InternalSpelExpressionParser.java        | 2 +-
 .../expression/spel/OperatorOverloaderTests.java           | 2 +-
 .../spel/ScenariosForSpringSecurityExpressionTests.java    | 2 +-
 .../org/springframework/expression/spel/SetValueTests.java | 6 +++---
 .../expression/spel/SpelCompilationCoverageTests.java      | 4 ++--
 .../springframework/expression/spel/SpelReproTests.java    | 2 +-
 15 files changed, 25 insertions(+), 24 deletions(-)

diff --git a/spring-expression/src/main/java/org/springframework/expression/ConstructorResolver.java b/spring-expression/src/main/java/org/springframework/expression/ConstructorResolver.java
index b8e1a2093f..821a46c1bd 100644
--- a/spring-expression/src/main/java/org/springframework/expression/ConstructorResolver.java
+++ b/spring-expression/src/main/java/org/springframework/expression/ConstructorResolver.java
@@ -22,7 +22,7 @@ import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.lang.Nullable;
 
 /**
- * A constructor resolver attempts locate a constructor and returns a ConstructorExecutor
+ * A constructor resolver attempts to locate a constructor and returns a ConstructorExecutor
  * that can be used to invoke that constructor. The ConstructorExecutor will be cached but
  * if it 'goes stale' the resolvers will be called again.
  *
diff --git a/spring-expression/src/main/java/org/springframework/expression/ParserContext.java b/spring-expression/src/main/java/org/springframework/expression/ParserContext.java
index 873d428a4a..86f1b2ba6f 100644
--- a/spring-expression/src/main/java/org/springframework/expression/ParserContext.java
+++ b/spring-expression/src/main/java/org/springframework/expression/ParserContext.java
@@ -27,7 +27,7 @@ package org.springframework.expression;
 public interface ParserContext {
 
 	/**
-	 * Whether or not the expression being parsed is a template. A template expression
+	 * Whether the expression being parsed is a template. A template expression
 	 * consists of literal text that can be mixed with evaluatable blocks. Some examples:
 	 * <pre class="code">
 	 * 	   Some literal text
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/CodeFlow.java b/spring-expression/src/main/java/org/springframework/expression/spel/CodeFlow.java
index 393946b216..8cde184626 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/CodeFlow.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/CodeFlow.java
@@ -171,7 +171,7 @@ public class CodeFlow implements Opcodes {
 
 	/**
 	 * Called after the main expression evaluation method has been generated, this
-	 * method will callback any registered FieldAdders or ClinitAdders to add any
+	 * method will call back any registered FieldAdders or ClinitAdders to add any
 	 * extra information to the class representing the compiled expression.
 	 */
 	public void finish() {
@@ -1008,7 +1008,7 @@ public class CodeFlow implements Opcodes {
 	/**
 	 * For use in mathematical operators, handles converting from a (possibly boxed)
 	 * number on the stack to a primitive numeric type.
-	 * <p>For example, from a Integer to a double, just need to call 'Number.doubleValue()'
+	 * <p>For example, from an Integer to a double, just need to call 'Number.doubleValue()'
 	 * but from an int to a double, need to use the bytecode 'i2d'.
 	 * @param mv the method visitor when instructions should be appended
 	 * @param stackDescriptor a descriptor of the operand on the stack
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/SpelNode.java b/spring-expression/src/main/java/org/springframework/expression/spel/SpelNode.java
index 1889f2ef12..6964d312eb 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/SpelNode.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/SpelNode.java
@@ -66,7 +66,7 @@ public interface SpelNode {
 	void setValue(ExpressionState expressionState, @Nullable Object newValue) throws EvaluationException;
 
 	/**
-	 * Return the string form the this AST node.
+	 * Return the string form of this AST node.
 	 * @return the string form
 	 */
 	String toStringAST();
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/ast/ConstructorReference.java b/spring-expression/src/main/java/org/springframework/expression/spel/ast/ConstructorReference.java
index c425c84746..35a0b3efc3 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/ast/ConstructorReference.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/ast/ConstructorReference.java
@@ -140,7 +140,7 @@ public class ConstructorReference extends SpelNodeImpl {
 
 				// To determine which situation it is, the AccessException will contain a cause.
 				// If the cause is an InvocationTargetException, a user exception was thrown inside the constructor.
-				// Otherwise the constructor could not be invoked.
+				// Otherwise, the constructor could not be invoked.
 				if (ex.getCause() instanceof InvocationTargetException) {
 					// User exception was the root cause - exit now
 					Throwable rootCause = ex.getCause().getCause();
@@ -271,7 +271,7 @@ public class ConstructorReference extends SpelNodeImpl {
 					newArray = Array.newInstance(componentType, arraySize);
 				}
 				else {
-					// Multi-dimensional - hold onto your hat!
+					// Multidimensional - hold onto your hat!
 					int[] dims = new int[this.dimensions.length];
 					long numElements = 1;
 					for (int d = 0; d < this.dimensions.length; d++) {
@@ -288,7 +288,7 @@ public class ConstructorReference extends SpelNodeImpl {
 		else {
 			// There is an initializer
 			if (this.dimensions == null || this.dimensions.length > 1) {
-				// There is an initializer but this is a multi-dimensional array (e.g. new int[][]{{1,2},{3,4}})
+				// There is an initializer but this is a multidimensional array (e.g. new int[][]{{1,2},{3,4}})
 				// - this is not currently supported
 				throw new SpelEvaluationException(getStartPosition(),
 						SpelMessage.MULTIDIM_ARRAY_INITIALIZER_NOT_SUPPORTED);
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/ast/Elvis.java b/spring-expression/src/main/java/org/springframework/expression/spel/ast/Elvis.java
index 60b313e90a..818f43fca6 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/ast/Elvis.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/ast/Elvis.java
@@ -26,8 +26,9 @@ import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
 
 /**
- * Represents the elvis operator ?:. For an expression "a?:b" if a is not null, the value
- * of the expression is "a", if a is null then the value of the expression is "b".
+ * Represents the elvis operator <code>?:</code>. For an expression <code>a?:b</code> if <code>a</code> is not null,
+ * the value of the expression is <code>a</code>, if <code>a</code> is null then the value of the expression is
+ * <code>b</code>.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
@@ -117,7 +118,7 @@ public class Elvis extends SpelNodeImpl {
 				this.exitTypeDescriptor = conditionDescriptor;
 			}
 			else {
-				// Use the easiest to compute common super type
+				// Use the easiest to compute common supertype
 				this.exitTypeDescriptor = "Ljava/lang/Object";
 			}
 		}
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/ast/OperatorInstanceof.java b/spring-expression/src/main/java/org/springframework/expression/spel/ast/OperatorInstanceof.java
index 0deb8b7da9..3cd663d873 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/ast/OperatorInstanceof.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/ast/OperatorInstanceof.java
@@ -29,8 +29,8 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
- * The operator 'instanceof' checks if an object is of the class specified in the right
- * hand operand, in the same way that {@code instanceof} does in Java.
+ * The operator 'instanceof' checks if an object is of the class specified in the
+ * right-hand operand, in the same way that {@code instanceof} does in Java.
  *
  * @author Andy Clement
  * @since 3.0
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/ast/PropertyOrFieldReference.java b/spring-expression/src/main/java/org/springframework/expression/spel/ast/PropertyOrFieldReference.java
index 476fb4c9b7..ec509199eb 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/ast/PropertyOrFieldReference.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/ast/PropertyOrFieldReference.java
@@ -164,7 +164,7 @@ public class PropertyOrFieldReference extends SpelNodeImpl {
 	/**
 	 * Attempt to read the named property from the current context object.
 	 * @return the value of the property
-	 * @throws EvaluationException if any problem accessing the property or it cannot be found
+	 * @throws EvaluationException if any problem accessing the property, or if it cannot be found
 	 */
 	private TypedValue readProperty(TypedValue contextObject, EvaluationContext evalContext, String name)
 			throws EvaluationException {
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/ast/Ternary.java b/spring-expression/src/main/java/org/springframework/expression/spel/ast/Ternary.java
index efb9b36897..2889f57942 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/ast/Ternary.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/ast/Ternary.java
@@ -74,7 +74,7 @@ public class Ternary extends SpelNodeImpl {
 				this.exitTypeDescriptor = leftDescriptor;
 			}
 			else {
-				// Use the easiest to compute common super type
+				// Use the easiest to compute common supertype
 				this.exitTypeDescriptor = "Ljava/lang/Object";
 			}
 		}
diff --git a/spring-expression/src/main/java/org/springframework/expression/spel/standard/InternalSpelExpressionParser.java b/spring-expression/src/main/java/org/springframework/expression/spel/standard/InternalSpelExpressionParser.java
index 5b3f69f781..33c4d9db4e 100644
--- a/spring-expression/src/main/java/org/springframework/expression/spel/standard/InternalSpelExpressionParser.java
+++ b/spring-expression/src/main/java/org/springframework/expression/spel/standard/InternalSpelExpressionParser.java
@@ -78,7 +78,7 @@ import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
 /**
- * Hand-written SpEL parser. Instances are reusable but are not thread-safe.
+ * Handwritten SpEL parser. Instances are reusable but are not thread-safe.
  *
  * @author Andy Clement
  * @author Juergen Hoeller
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/OperatorOverloaderTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/OperatorOverloaderTests.java
index d949e0733b..88e7b1e4e1 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/OperatorOverloaderTests.java
+++ b/spring-expression/src/test/java/org/springframework/expression/spel/OperatorOverloaderTests.java
@@ -35,7 +35,7 @@ public class OperatorOverloaderTests extends AbstractExpressionTests {
 
 	@Test
 	public void testSimpleOperations() throws Exception {
-		// no built in support for this:
+		// no built-in support for this:
 		evaluateAndCheckError("'abc'-true",SpelMessage.OPERATOR_NOT_SUPPORTED_BETWEEN_TYPES);
 
 		StandardEvaluationContext eContext = TestScenarioCreator.getTestEvaluationContext();
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/ScenariosForSpringSecurityExpressionTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/ScenariosForSpringSecurityExpressionTests.java
index 5d9798fae4..010da3e8f6 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/ScenariosForSpringSecurityExpressionTests.java
+++ b/spring-expression/src/test/java/org/springframework/expression/spel/ScenariosForSpringSecurityExpressionTests.java
@@ -123,7 +123,7 @@ public class ScenariosForSpringSecurityExpressionTests extends AbstractExpressio
 		SpelExpressionParser parser = new SpelExpressionParser();
 		StandardEvaluationContext ctx = new StandardEvaluationContext();
 
-		ctx.setRootObject(new Supervisor("Ben")); // so non-qualified references 'hasRole()' 'hasIpAddress()' are invoked against it);
+		ctx.setRootObject(new Supervisor("Ben")); // so non-qualified references 'hasRole()' 'hasIpAddress()' are invoked against it;
 
 		ctx.addMethodResolver(new MyMethodResolver()); // NEEDS TO OVERRIDE THE REFLECTION ONE - SHOW REORDERING MECHANISM
 		// Might be better with a as a variable although it would work as a property too...
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/SetValueTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/SetValueTests.java
index 6073d735b5..c79d286eea 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/SetValueTests.java
+++ b/spring-expression/src/test/java/org/springframework/expression/spel/SetValueTests.java
@@ -84,7 +84,7 @@ public class SetValueTests extends AbstractExpressionTests {
 		StandardEvaluationContext lContext = TestScenarioCreator.getTestEvaluationContext();
 
 		// PROPERTYORFIELDREFERENCE
-		// Non existent field (or property):
+		// Non-existent field (or property):
 		Expression e1 = parser.parseExpression("arrayContainer.wibble");
 		assertThat(e1.isWritable(lContext)).as("Should not be writable!").isFalse();
 
@@ -103,12 +103,12 @@ public class SetValueTests extends AbstractExpressionTests {
 		assertThat(e4.isWritable(lContext)).as("Should not be writable!").isFalse();
 
 		// INDEXER
-		// non existent indexer (wibble made up)
+		// non-existent indexer (wibble made up)
 		Expression e5 = parser.parseExpression("arrayContainer.wibble[99]");
 		assertThatExceptionOfType(SpelEvaluationException.class).isThrownBy(() ->
 				e5.isWritable(lContext));
 
-		// non existent indexer (index via a string)
+		// non-existent indexer (index via a string)
 		Expression e6 = parser.parseExpression("arrayContainer.ints['abc']");
 		assertThatExceptionOfType(SpelEvaluationException.class).isThrownBy(() ->
 				e6.isWritable(lContext));
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/SpelCompilationCoverageTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/SpelCompilationCoverageTests.java
index 98a726eff1..b55e9d1c61 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/SpelCompilationCoverageTests.java
+++ b/spring-expression/src/test/java/org/springframework/expression/spel/SpelCompilationCoverageTests.java
@@ -272,7 +272,7 @@ public class SpelCompilationCoverageTests extends AbstractExpressionTests {
 		assertCanCompile(expression);
 		assertThat(expression.getValue()).asInstanceOf(BOOLEAN).isTrue();
 
-		// Only when the right hand operand is a direct type reference
+		// Only when the right-hand operand is a direct type reference
 		// will it be compilable.
 		StandardEvaluationContext ctx = new StandardEvaluationContext();
 		ctx.setVariable("foo", String.class);
@@ -4155,7 +4155,7 @@ public class SpelCompilationCoverageTests extends AbstractExpressionTests {
 	void propertyReference() {
 		TestClass6 tc = new TestClass6();
 
-		// non static field
+		// non-static field
 		expression = parser.parseExpression("orange");
 		assertCantCompile(expression);
 		assertThat(expression.getValue(tc)).isEqualTo("value1");
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/SpelReproTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/SpelReproTests.java
index b4f0168f07..508358f445 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/SpelReproTests.java
+++ b/spring-expression/src/test/java/org/springframework/expression/spel/SpelReproTests.java
@@ -602,7 +602,7 @@ class SpelReproTests extends AbstractExpressionTests {
 	/**
 	 * Test whether {@link ReflectiveMethodResolver} follows Java Method Invocation
 	 * Conversion order. And more precisely that widening reference conversion is 'higher'
-	 * than a unboxing conversion.
+	 * than an unboxing conversion.
 	 */
 	@Test
 	void conversionPriority_SPR8224() throws Exception {