diff --git a/platform/annotations/common/src/org/jetbrains/annotations/Contract.java b/platform/annotations/common/src/org/jetbrains/annotations/Contract.java
index 3bbaadaaf4c7..efbed42c7df1 100644
--- a/platform/annotations/common/src/org/jetbrains/annotations/Contract.java
+++ b/platform/annotations/common/src/org/jetbrains/annotations/Contract.java
@@ -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