From 1e432ff95d79ff5f5402313a49884520097d8d89 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Fri, 2 Feb 2024 14:39:09 +0100
Subject: [PATCH] Improve documentation for overloaded operators in SpEL

See gh-32182
---
 .../ROOT/pages/core/expressions/evaluation.adoc |  1 +
 .../expressions/language-ref/operators.adoc     | 17 ++++++++++++++---
 .../expression/spel/SpelDocumentationTests.java |  4 ++--
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc
index db5494831b..43840d17d2 100644
--- a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc
+++ b/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.
diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc
index 488022a703..b533aa2bd5 100644
--- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc
+++ b/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.
+====
diff --git a/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java b/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java
index ddede6f1f0..aa6d6ec497 100644
--- a/spring-expression/src/test/java/org/springframework/expression/spel/SpelDocumentationTests.java
+++ b/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));
 		}
 	}