From 72e7f1552b8af1e877ecb3541568d91c1b634dc5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?= <sebastien.deleuze@broadcom.com>
Date: Wed, 6 Nov 2024 12:00:08 +0100
Subject: [PATCH] Refine `@Contract` Javadoc

This commit refines `@Contract` Javadoc to mention
this and new return values.

Closes gh-33849
---
 .../org/springframework/lang/Contract.java    | 55 ++++++++++++-------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/spring-core/src/main/java/org/springframework/lang/Contract.java b/spring-core/src/main/java/org/springframework/lang/Contract.java
index 6125b10fd83b..eff30e21e6fe 100644
--- a/spring-core/src/main/java/org/springframework/lang/Contract.java
+++ b/spring-core/src/main/java/org/springframework/lang/Contract.java
@@ -32,34 +32,47 @@
  * been introduce in the {@code org.springframework.lang} package to avoid requiring
  * an extra dependency, while still following the same semantics.
  *
- * <p>Method contract has the following syntax:<br/>
- *  contract ::= (clause ';')* clause<br/>
- *  clause ::= args '->' effect<br/>
- *  args ::= ((arg ',')* arg )?<br/>
- *  arg ::= value-constraint<br/>
- *  value-constraint ::= 'any' | 'null' | '!null' | 'false' | 'true'<br/>
- *  effect ::= value-constraint | 'fail'
+ * <p>Method contract has the following syntax:
+ * <pre>{@code
+ *  contract ::= (clause ';')* clause
+ *  clause ::= args '->' effect
+ *  args ::= ((arg ',')* arg )?
+ *  arg ::= value-constraint
+ *  value-constraint ::= '_' | 'null' | '!null' | 'false' | 'true'
+ *  effect ::= value-constraint | 'fail' | 'this' | 'new' | 'param<N>'}</pre>
  *
- * The constraints denote the following:<br/>
+ * <p>The constraints denote the following:
  * <ul>
- * <li> <code>_</code> - any value</li>
- * <li> <code>null</code> - null value</li>
- * <li> <code>!null</code> - a value statically proved to be not-null</li>
- * <li> <code>true</code> - true boolean value</li>
- * <li> <code>false</code> - false boolean value</li>
- * <li> <code>fail</code> - the method throws an exception, if the arguments satisfy argument
- * constraints</li>
+ * <li>{@code _} - any value
+ * <li>{@code null} - null value
+ * <li>{@code !null} - a value statically proved to be not-null
+ * <li>{@code true} - true boolean value
+ * <li>{@code false} - false boolean value
  * </ul>
+ *
+ * <p>The additional return values denote the following:
+ * <ul>
+ * <li>{@code fail} - the method throws an exception, if the arguments satisfy argument constraints
+ * <li>{@code new} - the method returns a non-null new object which is distinct from any other object existing in the heap prior to method execution. If method is also pure, then we can be sure that the new object is not stored to any field/array and will be lost if method return value is not used.
+ * <li>{@code this} - the method returns its qualifier value (not applicable for static methods)
+ * <li>{@code param1, param2, ...} - the method returns its first (second, ...) parameter value
+ * </ul>
+ *
  * <p>Examples:
- * <code>@Contract("_, null -> null")</code> - method returns null if its second
- * argument is null<br/>
- * <code>@Contract("_, null -> null; _, !null -> !null")</code> - method returns
- * null if its second argument is null and not-null otherwise<br/>
- * <code>@Contract("true -> fail")</code> - a typical assertFalse method which
- * throws an exception if <code>true</code> is passed to it<br/>
+ * <ul>
+ * <li>{@code @Contract("_, null -> null")} - the method returns null if its second argument is null.
+ * <li>{@code @Contract("_, null -> null; _, !null -> !null")} - the method returns null if its second argument is null and not-null otherwise.
+ * <li>{@code @Contract("true -> fail")} - a typical {@code assertFalse} method which throws an exception if {@code true} is passed to it.
+ * <li>{@code @Contract("_ -> this")} - the method always returns its qualifier (e.g. {@link StringBuilder#append(String)}).
+ * <li>{@code @Contract("null -> fail; _ -> param1")} - the method throws an exception if the first argument is null,
+ * otherwise it returns the first argument (e.g. {@code Objects.requireNonNull}).
+ * <li>{@code @Contract("!null, _ -> param1; null, !null -> param2; null, null -> fail")} - the method returns the first non-null argument,
+ * or throws an exception if both arguments are null (e.g. {@code Objects.requireNonNullElse}).
+ * </ul>
  *
  * @author Sebastien Deleuze
  * @since 6.2
+ * @see <a href="https://github.com/JetBrains/java-annotations/blob/master/src/jvmMain/java/org/jetbrains/annotations/Contract.java">org.jetbrains.annotations.Contract</a>
  * @see <a href="https://github.com/uber/NullAway/wiki/Configuration#custom-contract-annotations">
  * NullAway custom contract annotations</a>
  */