Skip to content

Commit

Permalink
Polish @Contract Javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
sdeleuze committed Oct 30, 2024
1 parent 09d87fa commit 74997b5
Showing 1 changed file with 20 additions and 13 deletions.
33 changes: 20 additions & 13 deletions spring-core/src/main/java/org/springframework/lang/Contract.java
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,14 @@
import java.lang.annotation.Target;

/**
* Inspired from {@code org.jetbrains.annotations.Contract}, this variant has been introduce in the
* {@code org.springframework.lang} package to avoid requiring an extra dependency, while still following the same semantics.
* <p>Specifies some aspects of the method behavior depending on the arguments.
* Can be used by tools for advanced data flow analysis. Note that this annotation
* just describes how the code works and doesn't add any functionality by means of
* code generation.
*
* <p>Specifies some aspects of the method behavior depending on the arguments. Can be used by tools for advanced data flow analysis.
* Note that this annotation just describes how the code works and doesn't add any functionality by means of code generation.
* <p>Inspired from {@code org.jetbrains.annotations.Contract}, this variant has
* 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/>
Expand All @@ -39,17 +42,21 @@
*
* The constraints denote the following:<br/>
* <ul>
* <li> _ - any value
* <li> null - null value
* <li> !null - a value statically proved to be not-null
* <li> true - true boolean value
* <li> false - false boolean value
* <li> fail - the method throws an exception, if the arguments satisfy argument constraints
* <li> _ - any value</li>
* <li> null - null value</li>
* <li> !null - a value statically proved to be not-null</li>
* <li> true - true boolean value</li>
* <li> false - false boolean value</li>
* <li> fail - the method throws an exception, if the arguments satisfy argument
* constraints</li>
* </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/>
* <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/>
*
* @author Sebastien Deleuze
* @since 6.2
Expand Down

0 comments on commit 74997b5

Please sign in to comment.