Improve documentation for overloaded operators in SpEL

See gh-32182

framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc

@@ -517,6 +517,7 @@ following kinds of expressions cannot be compiled.
 * Expressions involving assignment
 * Expressions relying on the conversion service
 * Expressions using custom resolvers or accessors
+* Expressions using overloaded operators
 * Expressions using selection or projection
 
 Compilation of additional kinds of expressions may be supported in the future.

framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc

@@ -559,7 +559,7 @@ follows.
 			}
 			throw new UnsupportedOperationException(
 				"No overload for operation %s and operands [%s] and [%s]"
-					.formatted(operation.name(), left, right));
+					.formatted(operation, left, right));
 		}
 	}
 ----
@@ -578,7 +578,7 @@ Java::
 	context.setOperatorOverloader(new ListConcatenation());
 
 	// evaluates to a new list: [1, 2, 3, 4, 5]
-	parser.parseExpression("{1, 2, 3} + {4, 5}").getValue(context, List.class);
+	parser.parseExpression("{1, 2, 3} + {2 + 2, 5}").getValue(context, List.class);
 ----
 
 Kotlin::
@@ -589,8 +589,19 @@ Kotlin::
 	context.setOperatorOverloader(ListConcatenation())
 
 	// evaluates to a new list: [1, 2, 3, 4, 5]
-	parser.parseExpression("{1, 2, 3} + {4, 5}").getValue(context, List::class.java)
+	parser.parseExpression("{1, 2, 3} + {2 + 2, 5}").getValue(context, List::class.java)
 ----
 ======
 
+[NOTE]
+====
+An `OperatorOverloader` does not change the default semantics for an operator. For
+example, `2 + 2` in the above example still evaluates to `4`.
+====
 
+[CAUTION]
+====
+Any expression that uses an overloaded operator cannot be compiled. See
+xref:core/expressions/evaluation.adoc#expressions-compiler-limitations[Compiler Limitations]
+for details.
+====

spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java

@@ -457,7 +457,7 @@ class SpelDocumentationTests extends AbstractExpressionTests {
 			context.setOperatorOverloader(new ListConcatenation());
 
 			// evaluates to [1, 2, 3, 4, 5]
-			List list = parser.parseExpression("{1, 2, 3} + {4, 5}").getValue(context, List.class);
+			List list = parser.parseExpression("{1, 2, 3} + {2 + 2, 5}").getValue(context, List.class);
 			assertThat(list).containsExactly(1, 2, 3, 4, 5);
 		}
 
@@ -706,7 +706,7 @@ class SpelDocumentationTests extends AbstractExpressionTests {
 			}
 			throw new UnsupportedOperationException(
 				"No overload for operation %s and operands [%s] and [%s]"
-					.formatted(operation.name(), left, right));
+					.formatted(operation, left, right));
 		}
 	}