MDS/openide
1
0
Fork 0
mirror of https://gitflic.ru/project/openide/openide.git synced 2026-09-27 10:03:11 +07:00
Code Issues Packages Projects Releases Wiki Activity

Contract annotation JavaDoc updated to reflect new values (IDEA-191302)

Browse Source
This commit is contained in:
Tagir Valeev
2018-05-10 12:27:45 +07:00
parent c4079a4c4e
commit 91744c248e
1 changed files with 22 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
platform/annotations/common/src/org/jetbrains/annotations/Contract.java
+22 -9
View File
@@ -23,12 +23,13 @@ import java.util.concurrent.atomic.AtomicBoolean;
* Note that this annotation just describes how the code works and doesn't add any functionality by means of code generation.<p>
*
* Method contract has the following syntax:<br>
* contract ::= (clause ';')* clause<br>
* clause ::= args '-&gt;' effect<br>
* args ::= ((arg ',')* arg )?<br>
* arg ::= value-constraint<br>
* value-constraint ::= '_' | 'null' | '!null' | 'false' | 'true'<br>
* effect ::= value-constraint | 'fail' <p>
* <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> <p>
*
* The constraints denote the following:<br>
* <ul>
@@ -37,12 +38,24 @@ import java.util.concurrent.atomic.AtomicBoolean;
* <li> !null - a value statically proved to be not-null
* <li> true - true boolean value
* <li> false - false boolean value
* </ul>
*
* The additional return values denote the following:<br>
* <ul>
* <li> fail - the method throws an exception, if the arguments satisfy argument constraints
* <li> new - (supported since IDEA 2018.2) 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> this - (supported since IDEA 2018.2) the method returns its qualifier value (not applicable for static methods)
* <li> param1, param2, ... - (supported since IDEA 2018.2) the method returns its first (second, ...) parameter value
* </ul>
* Examples:<p>
* {@code @Contract("_, null -> null")} - method returns null if its second argument is null<br>
* {@code @Contract("_, null -> null; _, !null -> !null")} - method returns null if its second argument is null and not-null otherwise<br>
* {@code @Contract("true -> fail")} - a typical assertFalse method which throws an exception if {@code true} is passed to it<br>
* {@code @Contract("_, null -> null")} - the method returns null if its second argument is null<br>
* {@code @Contract("_, null -> null; _, !null -> !null")} - the method returns null if its second argument is null and not-null otherwise<br>
* {@code @Contract("true -> fail")} - a typical {@code assertFalse} method which throws an exception if {@code true} is passed to it<br>
* {@code @Contract("_ -> this")} - the method always returns its qualifier (e.g. {@link StringBuilder#append(String)}).
* {@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}).<br>
* {@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} in Java 9).<br>
*
*/
@Documented