Improve contract API documentation

libraries/stdlib/src/kotlin/contracts/ContractBuilder.kt

@@ -22,7 +22,10 @@ import kotlin.internal.InlineOnly
 public annotation class ExperimentalContracts
 
 /**
- * The builder is used to specify contract effects for some function.
+ * Provides a scope, where the functions of the contract DSL, such as [returns], [callsInPlace], etc.,
+ * can be used to describe the contract of a function.
+ *
+ * This type is used as a receiver type of the lambda function passed to the [contract] function.
  *
  * @see contract
  */
@@ -31,15 +34,20 @@ public annotation class ExperimentalContracts
 @SinceKotlin("1.3")
 public interface ContractBuilder {
     /**
-     * Expresses that a function returned successfully.
+     * Describes a situation when a function returns normally, without any exceptions thrown.
+     *
+     * Use [SimpleEffect.implies] function to describe a conditional effect that happens in such case.
      *
      * @sample samples.contracts.returnsContract
      */
     @ContractsDsl public fun returns(): Returns
 
     /**
-     * Expresses that a function returned with some value.
-     * Value can only be `true`, `false` or `null`.
+     * Describes a situation when a function returns normally with the specified return [value].
+     *
+     * The possible values of [value] are limited to `true`, `false` or `null`.
+     *
+     * Use [SimpleEffect.implies] function to describe a conditional effect that happens in such case.
      *
      * @sample samples.contracts.returnsTrueContract
      * @sample samples.contracts.returnsFalseContract
@@ -48,20 +56,24 @@ public interface ContractBuilder {
     @ContractsDsl public fun returns(value: Any?): Returns
 
     /**
-     * Expresses that a function returned with any not null value.
+     * Describes a situation when a function returns normally with any value that is not `null`.
+     *
+     * Use [SimpleEffect.implies] function to describe a conditional effect that happens in such case.
      *
      * @sample samples.contracts.returnsNotNullContract
      */
     @ContractsDsl public fun returnsNotNull(): ReturnsNotNull
 
     /**
-     * Expresses that:
-     *  1) [lambda] will not be called after the call to owner-function is finished;
-     *  2) [lambda] will not be passed to another function without the similar contract.
+     * Specifies that the function parameter [lambda] is invoked in place.
      *
-     * @param kind amount of times, that a [lambda] guaranteed will be invoked.
+     * This contract specifies that:
+     * 1. the function [lambda] can only be invoked during the call of the owner function,
+     *  and it won't be invoked after that owner function call is completed;
+     * 2. _(optionally)_ the function [lambda] is invoked the amount of times specified by the [kind] parameter,
+     *  see the [InvocationKind] enum for possible values.
      *
-     * Note that a function with the `callsInPlace` effect must be inline.
+     * A function declaring the `callsInPlace` effect must be _inline_.
      *
      * @sample samples.contracts.callsInPlaceAtMostOnceContract
      * @sample samples.contracts.callsInPlaceAtLeastOnceContract
@@ -72,35 +84,37 @@ public interface ContractBuilder {
 }
 
 /**
- * This enum class is used to specify the amount of times, that `callable` which is used in the [ContractBuilder.callsInPlace] effect guaranteed will be invoked.
+ * Specifies how many times a function invokes its function parameter in place.
+ *
+ * See [ContractBuilder.callsInPlace] for the details of the call-in-place function contract.
  */
 @ContractsDsl
 @ExperimentalContracts
 @SinceKotlin("1.3")
 public enum class InvocationKind {
     /**
-     * Expresses that the `callable` will be invoked zero or one time.
+     * A function parameter will be invoked one time or not invoked at all.
      *
      * @sample samples.contracts.callsInPlaceAtMostOnceContract
      */
     @ContractsDsl AT_MOST_ONCE,
 
     /**
-     * Expresses that the `callable` will be invoked one or more times.
+     * A function parameter will be invoked one or more times.
      *
      * @sample samples.contracts.callsInPlaceAtLeastOnceContract
      */
     @ContractsDsl AT_LEAST_ONCE,
 
     /**
-     * Expresses that the `callable` will be invoked exactly one time.
+     * A function parameter will be invoked exactly one time.
      *
      * @sample samples.contracts.callsInPlaceExactlyOnceContract
      */
     @ContractsDsl EXACTLY_ONCE,
 
     /**
-     * Expresses that the `callable` will be invoked unknown amount of times.
+     * A function parameter is called in place, but it's unknown how many times it can be called.
      *
      * @sample samples.contracts.callsInPlaceUnknownContract
      */
@@ -108,11 +122,13 @@ public enum class InvocationKind {
 }
 
 /**
- * The function to describe a contract.
- * The contract description must be at the beginning of a function and has at least one effect.
- * Also the contract description can be used only in the top-level functions.
+ * Specifies the contact of a function.
  *
- * @param builder the lambda in the body of which the effects from the [ContractBuilder] are specified.
+ * The contract description must be at the beginning of a function and have at least one effect.
+ *
+ * Only the top-level functions can have a contract for now.
+ *
+ * @param builder the lambda where the contract of a function is described with the help of the [ContractBuilder] members.
  *
  * @sample samples.contracts.returnsContract
  * @sample samples.contracts.returnsTrueContract

libraries/stdlib/src/kotlin/contracts/Effect.kt

@@ -8,7 +8,15 @@ package kotlin.contracts
 import kotlin.internal.ContractsDsl
 
 /**
- * Abstract effect, the inheritors of which are used in [ContractBuilder] to describe the contract function.
+ * Represents an effect of a function invocation,
+ * either directly observable, such as the function returning normally,
+ * or a side-effect, such as the function's lambda parameter being called in place.
+ *
+ * The inheritors are used in [ContractBuilder] to describe the contract of a function.
+ *
+ * @see ConditionalEffect
+ * @see SimpleEffect
+ * @see CallsInPlace
  */
 @ContractsDsl
 @ExperimentalContracts
@@ -16,10 +24,10 @@ import kotlin.internal.ContractsDsl
 public interface Effect
 
 /**
- * This interface corresponds to an additional condition applied to the [SimpleEffect].
- * Can only be used in conjunction with [SimpleEffect].
+ * An effect of some condition being true after observing another effect of a function.
  *
- * @see SimpleEffect.implies
+ * This effect is specified in the `contract { }` block by attaching a boolean expression
+ * to another [SimpleEffect] effect with the function [SimpleEffect.implies].
  */
 @ContractsDsl
 @ExperimentalContracts
@@ -27,18 +35,24 @@ public interface Effect
 public interface ConditionalEffect : Effect
 
 /**
- * Describes of function's behavior regardless of any conditions.
+ * An effect that can be observed after a function invocation.
+ *
+ * @see ContractBuilder.returns
+ * @see ContractBuilder.returnsNotNull
  */
 @ContractsDsl
 @ExperimentalContracts
 @SinceKotlin("1.3")
 public interface SimpleEffect : Effect {
     /**
-     * The function to specify an additional condition for some `SimpleEffect`.
+     * Specifies that this effect, when observed, guarantees [booleanExpression] to be true.
      *
-     * @param booleanExpression the additional condition which is a subset of the Kotlin boolean expressions.
-     *
-     * Note: the subset of the Kotlin boolean expressions is true/false/null checks (using the equality expression) for a function parameter or receiver, also allowed the conjunction and disjunction.
+     * Note: [booleanExpression] can accept only a subset of boolean expressions,
+     * where a function parameter or receiver (`this`) undergoes
+     * - true of false checks, in case if the parameter or receiver is `Boolean`;
+     * - null-checks (`== null`, `!= null`);
+     * - instance-checks (`is`, `!is`);
+     * - a combination of the above with the help of logic operators (`&&`, `||`, `!`).
      */
     @ContractsDsl
     @ExperimentalContracts
@@ -46,8 +60,7 @@ public interface SimpleEffect : Effect {
 }
 
 /**
- * Describes the return value of a function.
- * The return value can only be `true`, `false` or `null`.
+ * Describes a situation when a function returns normally with a given return value.
  *
  * @see ContractBuilder.returns
  */
@@ -57,7 +70,7 @@ public interface SimpleEffect : Effect {
 public interface Returns : SimpleEffect
 
 /**
- * Describes that the return value of a function is not null.
+ * Describes a situation when a function returns normally with any non-null return value.
  *
  * @see ContractBuilder.returnsNotNull
  */
@@ -67,7 +80,11 @@ public interface Returns : SimpleEffect
 public interface ReturnsNotNull : SimpleEffect
 
 /**
- * Describes of function's behavior in relation to the invocation of the received lambda.
+ * An effect of calling a functional parameter in place.
+ *
+ * A function is said to call its functional parameter in place, if the functional parameter is only invoked
+ * while the execution has not been returned from the function, and the functional parameter cannot be
+ * invoked after the function is completed.
  *
  * @see ContractBuilder.callsInPlace
  */