Unify stdlib docs with common stdlib (#2245)

* Update collection interface declarations

* Unify math docs: remove excess 'actual' word

* Unify print/println/readLine docs

* Unify annotations docs

* Correct parameter reference in copyInto docs

* Unify array extension docs

* Unify AbstractMutableMap docs

* Unify docs of primitives and string extensions

* Unify coroutine intrinsic docs

* Unify Regex docs

runtime/src/main/kotlin/kotlin/Annotations.kt

@@ -118,7 +118,15 @@ public annotation class SinceKotlin(val version: String)
 public annotation class DslMarker
 
 /**
- * Specifies that this part of internal API is effectively public exposed by using in public inline function
+ * When applied to a class or a member with internal visibility allows to use it from public inline functions and
+ * makes it effectively public.
+ *
+ * Public inline functions cannot use non-public API, since if they are inlined, those non-public API references
+ * would violate access restrictions at a call site (http://kotlinlang.org/docs/reference/inline-functions.html#public-inline-restrictions).
+ *
+ * To overcome this restriction an `internal` declaration can be annotated with the `@PublishedApi` annotation:
+ * - this allows to call that declaration from public inline functions;
+ * - the declaration becomes effectively public, and this should be considered with respect to binary compatibility maintaining.
  */
 @Target(AnnotationTarget.CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
 @Retention(AnnotationRetention.BINARY)

runtime/src/main/kotlin/kotlin/Boolean.kt

@@ -22,13 +22,15 @@ public class Boolean private constructor(
     external public operator fun not(): Boolean
 
     /**
-     * Performs a logical `and` operation between this Boolean and the [other] one.
+     * Performs a logical `and` operation between this Boolean and the [other] one. Unlike the `&&` operator,
+     * this function does not perform short-circuit evaluation. Both `this` and [other] will always be evaluated.
      */
     @SymbolName("Kotlin_Boolean_and_Boolean")
     external public infix fun and(other: Boolean): Boolean
 
     /**
-     * Performs a logical `or` operation between this Boolean and the [other] one.
+     * Performs a logical `or` operation between this Boolean and the [other] one. Unlike the `||` operator,
+     * this function does not perform short-circuit evaluation. Both `this` and [other] will always be evaluated.
      */
     @SymbolName("Kotlin_Boolean_or_Boolean")
     external public infix fun or(other: Boolean): Boolean

runtime/src/main/kotlin/kotlin/Char.kt

@@ -12,8 +12,9 @@ public class Char private constructor(
         private val value: kotlin.native.internal.ShortValue) : Comparable<Char> {
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     *
-     * or a positive number if its greater than other.
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Char_compareTo_Char")
     external public override fun compareTo(other: Char): Int

runtime/src/main/kotlin/kotlin/Primitives.kt

@@ -38,43 +38,43 @@ public final class Byte private constructor(private val value: kotlin.native.int
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Byte_compareTo_Byte")
     external public override operator fun compareTo(other: Byte): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Byte_compareTo_Short")
     external public operator fun compareTo(other: Short): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Byte_compareTo_Int")
     external public operator fun compareTo(other: Int): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Byte_compareTo_Long")
     external public operator fun compareTo(other: Long): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Byte_compareTo_Float")
     external public operator fun compareTo(other: Float): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Byte_compareTo_Double")
     external public operator fun compareTo(other: Double): Int
@@ -263,43 +263,43 @@ public final class Short private constructor(private val value: kotlin.native.in
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Short_compareTo_Byte")
     external public operator fun compareTo(other: Byte): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Short_compareTo_Short")
     external public override operator fun compareTo(other: Short): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Short_compareTo_Int")
     external public operator fun compareTo(other: Int): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Short_compareTo_Long")
     external public operator fun compareTo(other: Long): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Short_compareTo_Float")
     external public operator fun compareTo(other: Float): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Short_compareTo_Double")
     external public operator fun compareTo(other: Double): Int
@@ -488,43 +488,43 @@ public final class Int private constructor(private val value: kotlin.native.inte
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Int_compareTo_Byte")
     external public operator fun compareTo(other: Byte): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Int_compareTo_Short")
     external public operator fun compareTo(other: Short): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Int_compareTo_Int")
     external public override operator fun compareTo(other: Int): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Int_compareTo_Long")
     external public operator fun compareTo(other: Long): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Int_compareTo_Float")
     external public operator fun compareTo(other: Float): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Int_compareTo_Double")
     external public operator fun compareTo(other: Double): Int
@@ -637,13 +637,13 @@ public final class Int private constructor(private val value: kotlin.native.inte
     @SymbolName("Kotlin_Int_unaryMinus")
     external public operator fun unaryMinus(): Int
 
-    /** Shifts this value left by [bits]. */
+    /** Shifts this value left by the [bitCount] number of bits. */
     @SymbolName("Kotlin_Int_shl_Int")
     external public infix fun shl(bitCount: Int): Int
-    /** Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit. */
+    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit. */
     @SymbolName("Kotlin_Int_shr_Int")
     external public infix fun shr(bitCount: Int): Int
-    /** Shifts this value right by [bits], filling the leftmost bits with zeros. */
+    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros. */
     @SymbolName("Kotlin_Int_ushr_Int")
     external public infix fun ushr(bitCount: Int): Int
     /** Performs a bitwise AND operation between the two values. */
@@ -655,7 +655,7 @@ public final class Int private constructor(private val value: kotlin.native.inte
     /** Performs a bitwise XOR operation between the two values. */
     @SymbolName("Kotlin_Int_xor_Int")
     external public infix fun xor(other: Int): Int
-    /** Inverts the bits in this value/ */
+    /** Inverts the bits in this value. */
     @SymbolName("Kotlin_Int_inv")
     external public fun inv(): Int
 
@@ -735,43 +735,43 @@ public final class Long private constructor(private val value: kotlin.native.int
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Long_compareTo_Byte")
     external public operator fun compareTo(other: Byte): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Long_compareTo_Short")
     external public operator fun compareTo(other: Short): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Long_compareTo_Int")
     external public operator fun compareTo(other: Int): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Long_compareTo_Long")
     external public override operator fun compareTo(other: Long): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Long_compareTo_Float")
     external public operator fun compareTo(other: Float): Int
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     @SymbolName("Kotlin_Long_compareTo_Double")
     external public operator fun compareTo(other: Double): Int
@@ -901,13 +901,13 @@ public final class Long private constructor(private val value: kotlin.native.int
         return LongRange(this, other.toLong())
     }
 
-    /** Shifts this value left by [bits]. */
+    /** Shifts this value left by the [bitCount] number of bits. */
     @SymbolName("Kotlin_Long_shl_Int")
     external public infix fun shl(bitCount: Int): Long
-    /** Shifts this value right by [bits], filling the leftmost bits with copies of the sign bit. */
+    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit. */
     @SymbolName("Kotlin_Long_shr_Int")
     external public infix fun shr(bitCount: Int): Long
-    /** Shifts this value right by [bits], filling the leftmost bits with zeros. */
+    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros. */
     @SymbolName("Kotlin_Long_ushr_Int")
     external public infix fun ushr(bitCount: Int): Long
     /** Performs a bitwise AND operation between the two values. */
@@ -919,7 +919,7 @@ public final class Long private constructor(private val value: kotlin.native.int
     /** Performs a bitwise XOR operation between the two values. */
     @SymbolName("Kotlin_Long_xor_Long")
     external public infix fun xor(other: Long): Long
-    /** Inverts the bits in this value/ */
+    /** Inverts the bits in this value. */
     @SymbolName("Kotlin_Long_inv")
     external public fun inv(): Long
 
@@ -987,32 +987,32 @@ public final class Float private constructor(private val value: kotlin.native.in
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Byte): Int = compareTo(other.toFloat())
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Short): Int = compareTo(other.toFloat())
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Int): Int = compareTo(other.toFloat())
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Long): Int = compareTo(other.toFloat())
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public override operator fun compareTo(other: Float): Int {
         // if any of values in NaN both comparisons return false
@@ -1028,8 +1028,8 @@ public final class Float private constructor(private val value: kotlin.native.in
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Double): Int = - other.compareTo(this)
 
@@ -1206,43 +1206,43 @@ public final class Double private constructor(private val value: kotlin.native.i
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Byte): Int = compareTo(other.toDouble())
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Short): Int = compareTo(other.toDouble())
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Int): Int = compareTo(other.toDouble())
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Long): Int = compareTo(other.toDouble())
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public operator fun compareTo(other: Float): Int = compareTo(other.toDouble())
 
     /**
      * Compares this value with the specified value for order.
-     * Returns zero if this value is equal to the specified other value, a negative number if its less than other,
+     * Returns zero if this value is equal to the specified other value, a negative number if it's less than other,
-     * or a positive number if its greater than other.
+     * or a positive number if it's greater than other.
      */
     public override operator fun compareTo(other: Double): Int {
         // if any of values in NaN both comparisons return false

runtime/src/main/kotlin/kotlin/annotation/Annotations.kt

@@ -5,6 +5,8 @@
 
 package kotlin.annotation
 
+import kotlin.annotation.AnnotationTarget.*
+
 /**
  * Contains the list of code elements which are the possible annotation targets
  */
@@ -59,8 +61,8 @@ public enum class AnnotationRetention {
 /**
  * This meta-annotation indicates the kinds of code elements which are possible targets of an annotation.
  *
- * If the target meta-annotation is not present on an annotation declaration, the annotation
+ * If the target meta-annotation is not present on an annotation declaration, the annotation is applicable to the following elements:
- * is applicable to any code element, except type parameters, type usages, expressions, and files.
+ * [CLASS], [PROPERTY], [FIELD], [LOCAL_VARIABLE], [VALUE_PARAMETER], [CONSTRUCTOR], [FUNCTION], [PROPERTY_GETTER], [PROPERTY_SETTER].
  *
  * @property allowedTargets list of allowed annotation targets
  */

runtime/src/main/kotlin/kotlin/collections/Arrays.kt

@@ -89,6 +89,12 @@ public actual inline fun CharArray.copyOf(): CharArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with `null` values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with `null` values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizingCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun <T> Array<T>.copyOf(newSize: Int): Array<T?> {
@@ -97,6 +103,12 @@ public actual inline fun <T> Array<T>.copyOf(newSize: Int): Array<T?> {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with zero values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ByteArray.copyOf(newSize: Int): ByteArray {
@@ -105,6 +117,12 @@ public actual inline fun ByteArray.copyOf(newSize: Int): ByteArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with zero values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ShortArray.copyOf(newSize: Int): ShortArray {
@@ -113,6 +131,12 @@ public actual inline fun ShortArray.copyOf(newSize: Int): ShortArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with zero values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun IntArray.copyOf(newSize: Int): IntArray {
@@ -121,6 +145,12 @@ public actual inline fun IntArray.copyOf(newSize: Int): IntArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with zero values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun LongArray.copyOf(newSize: Int): LongArray {
@@ -129,6 +159,12 @@ public actual inline fun LongArray.copyOf(newSize: Int): LongArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with zero values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun FloatArray.copyOf(newSize: Int): FloatArray {
@@ -137,6 +173,12 @@ public actual inline fun FloatArray.copyOf(newSize: Int): FloatArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with zero values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with zero values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun DoubleArray.copyOf(newSize: Int): DoubleArray {
@@ -145,6 +187,12 @@ public actual inline fun DoubleArray.copyOf(newSize: Int): DoubleArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with `false` values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with `false` values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun BooleanArray.copyOf(newSize: Int): BooleanArray {
@@ -153,6 +201,12 @@ public actual inline fun BooleanArray.copyOf(newSize: Int): BooleanArray {
 
 /**
  * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * The copy is either truncated or padded at the end with null char (`\u0000`) values if necessary.
+ *
+ * - If [newSize] is less than the size of the original array, the copy array is truncated to the [newSize].
+ * - If [newSize] is greater than the size of the original array, the extra elements in the copy array are filled with null char (`\u0000`) values.
+ *
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun CharArray.copyOf(newSize: Int): CharArray {
@@ -167,7 +221,10 @@ public actual inline fun CharArray.copyOf(newSize: Int): CharArray {
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 // TODO: The method may check input or return Array<T?>.
 // Now we check its input (fromIndex <= toIndex < size).
@@ -179,7 +236,10 @@ public actual inline fun <T> Array<T>.copyOfRange(fromIndex: Int, toIndex: Int):
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray {
@@ -188,7 +248,10 @@ public actual inline fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): By
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArray {
@@ -197,7 +260,10 @@ public actual inline fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): S
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray {
@@ -206,7 +272,10 @@ public actual inline fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): Int
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray {
@@ -215,7 +284,10 @@ public actual inline fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): Lo
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArray {
@@ -224,7 +296,10 @@ public actual inline fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): F
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleArray {
@@ -233,7 +308,10 @@ public actual inline fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int):
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): BooleanArray {
@@ -242,7 +320,10 @@ public actual inline fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int):
 }
 
 /**
- * Returns new array which is a copy of range of original array.
+ * Returns a new array which is a copy of the specified range of the original array.
+ *
+ * @param fromIndex the start of the range (inclusive), must be in `0..array.size`
+ * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size`
  */
 @kotlin.internal.InlineOnly
 public actual inline fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray {
@@ -259,8 +340,6 @@ public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit
 
 /**
  * Sorts the array in-place according to the natural order of its elements.
- *
- * @throws ClassCastException if any element of the array is not [Comparable].
  */
 public actual fun <T: Comparable<T>> Array<out T>.sort(): Unit {
     if (size > 1) sortArrayComparable(this)
@@ -615,7 +694,7 @@ public inline fun <T> Array<out T>.subarrayContentToString(offset: Int, length:
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -637,7 +716,7 @@ public actual fun <T> Array<out T>.copyInto(destination: Array<T>, destinationOf
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -659,7 +738,7 @@ public actual fun ByteArray.copyInto(destination: ByteArray, destinationOffset:
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -681,7 +760,7 @@ public actual fun ShortArray.copyInto(destination: ShortArray, destinationOffset
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -703,7 +782,7 @@ public actual fun IntArray.copyInto(destination: IntArray, destinationOffset: In
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -725,7 +804,7 @@ public actual fun LongArray.copyInto(destination: LongArray, destinationOffset:
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -747,7 +826,7 @@ public actual fun FloatArray.copyInto(destination: FloatArray, destinationOffset
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -769,7 +848,7 @@ public actual fun DoubleArray.copyInto(destination: DoubleArray, destinationOffs
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.
@@ -791,7 +870,7 @@ public actual fun BooleanArray.copyInto(destination: BooleanArray, destinationOf
  * @param endIndex the end (exclusive) of the subrange to copy, size of this array by default.
  *
  * @throws IndexOutOfBoundsException or [IllegalArgumentException] when [startIndex] or [endIndex] is out of range of this array indices or when `startIndex > endIndex`.
- * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationIndex],
+ * @throws IndexOutOfBoundsException when the subrange doesn't fit into the [destination] array starting at the specified [destinationOffset],
  * or when that index is out of the [destination] array indices range.
  *
  * @return the [destination] array.

runtime/src/main/kotlin/kotlin/collections/Collection.kt

@@ -8,7 +8,7 @@ package kotlin.collections
 /**
  * A generic collection of elements. Methods in this interface support only read-only access to the collection;
  * read/write access is supported through the [MutableCollection] interface.
- * @param E the type of elements contained in the collection.
+ * @param E the type of elements contained in the collection. The collection is covariant on its element type.
  */
 public interface Collection<out E> : Iterable<E> {
     // Query Operations
@@ -37,6 +37,8 @@ public interface Collection<out E> : Iterable<E> {
 
 /**
  * A generic collection of elements that supports adding and removing elements.
+ *
+ * @param E the type of elements contained in the collection. The mutable collection is invariant on its element type.
  */
 public interface MutableCollection<E> : Collection<E>, MutableIterable<E> {
     // Query Operations
@@ -61,7 +63,7 @@ public interface MutableCollection<E> : Collection<E>, MutableIterable<E> {
 
     // Bulk Modification Operations
     /**
-     * Adds all of the elements in the specified collection to this collection.
+     * Adds all of the elements of the specified collection to this collection.
      *
      * @return `true` if any of the specified elements was added to the collection, `false` if the collection was not modified.
      */

runtime/src/main/kotlin/kotlin/collections/Collections.kt

@@ -21,7 +21,7 @@ internal actual fun <T> Array<out T>.copyToArrayOfAny(isVarargs: Boolean): Array
 /**
  * Classes that inherit from this interface can be represented as a sequence of elements that can
  * be iterated over.
- * @param T the type of element being iterated over.
+ * @param T the type of element being iterated over. The iterator is covariant on its element type.
  */
 public interface Iterable<out T> {
     /**
@@ -33,10 +33,11 @@ public interface Iterable<out T> {
 /**
  * Classes that inherit from this interface can be represented as a sequence of elements that can
  * be iterated over and that supports removing elements during iteration.
+ * @param T the type of element being iterated over. The mutable iterator is invariant on its element type.
  */
 public interface MutableIterable<out T> : Iterable<T> {
     /**
-     * Returns an iterator over the elementrs of this sequence that supports removing elements during iteration.
+     * Returns an iterator over the elements of this sequence that supports removing elements during iteration.
      */
     override fun iterator(): MutableIterator<T>
 }

runtime/src/main/kotlin/kotlin/collections/List.kt

@@ -6,10 +6,10 @@
 package kotlin.collections
 
 /**
-* A generic ordered collection of elements. Methods in this interface support only read-only access to the list;
+ * A generic ordered collection of elements. Methods in this interface support only read-only access to the list;
-* read/write access is supported through the [MutableList] interface.
+ * read/write access is supported through the [MutableList] interface.
-* @param E the type of elements contained in the list.
+ * @param E the type of elements contained in the list. The list is covariant on its element type.
-*/
+ */
 public interface List<out E> : Collection<E> {
     // Query Operations
     override val size: Int
@@ -54,28 +54,44 @@ public interface List<out E> : Collection<E> {
     /**
      * Returns a view of the portion of this list between the specified [fromIndex] (inclusive) and [toIndex] (exclusive).
      * The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa.
+     *
+     * Structural changes in the base list make the behavior of the view undefined.
      */
     public fun subList(fromIndex: Int, toIndex: Int): List<E>
 }
 
 /**
  * A generic ordered collection of elements that supports adding and removing elements.
- * @param E the type of elements contained in the list.
+ * @param E the type of elements contained in the list. The mutable list is invariant on its element type.
  */
 public interface MutableList<E> : List<E>, MutableCollection<E> {
     // Modification Operations
+    /**
+     * Adds the specified element to the end of this list.
+     *
+     * @return `true` because the list is always modified as the result of this operation.
+     */
     override fun add(element: E): Boolean
+
     override fun remove(element: E): Boolean
 
     // Bulk Modification Operations
+    /**
+     * Adds all of the elements of the specified collection to the end of this list.
+     *
+     * The elements are appended in the order they appear in the [elements] collection.
+     *
+     * @return `true` if the list was changed as the result of the operation.
+     */
     override fun addAll(elements: Collection<E>): Boolean
 
     /**
-     * Inserts all of the elements in the specified collection [elements] into this list at the specified [index].
+     * Inserts all of the elements of the specified collection [elements] into this list at the specified [index].
      *
      * @return `true` if the list was changed as the result of the operation.
      */
     public fun addAll(index: Int, elements: Collection<E>): Boolean
+
     override fun removeAll(elements: Collection<E>): Boolean
     override fun retainAll(elements: Collection<E>): Boolean
     override fun clear(): Unit
@@ -102,6 +118,7 @@ public interface MutableList<E> : List<E>, MutableCollection<E> {
 
     // List Iterators
     override fun listIterator(): MutableListIterator<E>
+
     override fun listIterator(index: Int): MutableListIterator<E>
 
     // View

runtime/src/main/kotlin/kotlin/collections/Map.kt

@@ -10,8 +10,9 @@ package kotlin.collections
  * the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
  * Methods in this interface support only read-only access to the map; read-write access is supported through
  * the [MutableMap] interface.
- * @param K the type of map keys.
+ * @param K the type of map keys. The map is invariant on its key type, as it
- * @param V the type of map values.
+ *          can accept key as a parameter (of [containsKey] for example) and return it in [keys] set.
+ * @param V the type of map values. The map is covariant on its value type.
  */
 public interface Map<K, out V> {
     // Query Operations
@@ -42,17 +43,17 @@ public interface Map<K, out V> {
 
     // Views
     /**
-     * Returns a [Set] of all keys in this map.
+     * Returns a read-only [Set] of all keys in this map.
      */
     public val keys: Set<K>
 
     /**
-     * Returns a [Collection] of all values in this map. Note that this collection may contain duplicate values.
+     * Returns a read-only [Collection] of all values in this map. Note that this collection may contain duplicate values.
      */
     public val values: Collection<V>
 
     /**
-     * Returns a [Set] of all key/value pairs in this map.
+     * Returns a read-only [Set] of all key/value pairs in this map.
      */
     public val entries: Set<Map.Entry<K, V>>
 
@@ -75,8 +76,8 @@ public interface Map<K, out V> {
 /**
  * A modifiable collection that holds pairs of objects (keys and values) and supports efficiently retrieving
  * the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
- * @param K the type of map keys.
+ * @param K the type of map keys. The map is invariant on its key type.
- * @param V the type of map values.
+ * @param V the type of map values. The mutable map is invariant on its value type.
  */
 public interface MutableMap<K, V> : Map<K, V> {
     // Modification Operations
@@ -106,14 +107,25 @@ public interface MutableMap<K, V> : Map<K, V> {
     public fun clear(): Unit
 
     // Views
+    /**
+     * Returns a [MutableSet] of all keys in this map.
+     */
     override val keys: MutableSet<K>
+
+    /**
+     * Returns a [MutableCollection] of all values in this map. Note that this collection may contain duplicate values.
+     */
     override val values: MutableCollection<V>
+
+    /**
+     * Returns a [MutableSet] of all key/value pairs in this map.
+     */
     override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
 
     /**
      * Represents a key/value pair held by a [MutableMap].
      */
-    public interface MutableEntry<K,V>: Map.Entry<K, V> {
+    public interface MutableEntry<K, V> : Map.Entry<K, V> {
         /**
          * Changes the value associated with the key of this entry.
          *

runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt

@@ -46,12 +46,12 @@ actual abstract class AbstractMutableMap<K, V> protected actual constructor() :
     actual abstract override fun put(key: K, value: V): V?
 
     /**
-     * Returns a [Set] of all keys in this map.
+     * Returns a [MutableSet] of all keys in this map.
      */
     abstract override val keys: MutableSet<K>
 
     /**
-     * Returns a [Collection] of all values in this map.
+     * Returns a [MutableCollection] of all values in this map. Note that this collection may contain duplicate values.
      */
     abstract override val values: MutableCollection<V>
 }

runtime/src/main/kotlin/kotlin/collections/Set.kt

@@ -9,11 +9,12 @@ package kotlin.collections
  * A generic unordered collection of elements that does not support duplicate elements.
  * Methods in this interface support only read-only access to the set;
  * read/write access is supported through the [MutableSet] interface.
- * @param E the type of elements contained in the set.
+ * @param E the type of elements contained in the set. The set is covariant on its element type.
  */
 public interface Set<out E> : Collection<E> {
     // Query Operations
     override val size: Int
+
     override fun isEmpty(): Boolean
     override fun contains(element: @UnsafeVariance E): Boolean
     override fun iterator(): Iterator<E>
@@ -25,7 +26,7 @@ public interface Set<out E> : Collection<E> {
 /**
  * A generic unordered collection of elements that does not support duplicate elements, and supports
  * adding and removing elements.
- * @param E the type of elements contained in the set.
+ * @param E the type of elements contained in the set. The mutable set is invariant on its element type.
  */
 public interface MutableSet<E> : Set<E>, MutableCollection<E> {
     // Query Operations
@@ -33,10 +34,12 @@ public interface MutableSet<E> : Set<E>, MutableCollection<E> {
 
     // Modification Operations
     override fun add(element: E): Boolean
+
     override fun remove(element: E): Boolean
 
     // Bulk Modification Operations
     override fun addAll(elements: Collection<E>): Boolean
+
     override fun removeAll(elements: Collection<E>): Boolean
     override fun retainAll(elements: Collection<E>): Boolean
     override fun clear(): Unit

runtime/src/main/kotlin/kotlin/coroutines/intrinsics/IntrinsicsNative.kt

@@ -13,7 +13,12 @@ import kotlin.native.internal.*
  * Starts unintercepted coroutine without receiver and with result type [T] and executes it until its first suspension.
  * Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends.
  * In the later case, the [completion] continuation is invoked when coroutine completes with result or exception.
- * This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended
+ *
+ * The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might
+ * be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation
+ * context is established.
+ *
+ * This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended
  * coroutine using a reference to the suspending function.
  */
 @Suppress("UNCHECKED_CAST")
@@ -26,7 +31,12 @@ public actual inline fun <T> (suspend () -> T).startCoroutineUninterceptedOrRetu
  * Starts unintercepted coroutine with receiver type [R] and result type [T] and executes it until its first suspension.
  * Returns the result of the coroutine or throws its exception if it does not suspend or [COROUTINE_SUSPENDED] if it suspends.
  * In the later case, the [completion] continuation is invoked when coroutine completes with result or exception.
- * This function is designed to be used from inside of [suspendCoroutineOrReturn] to resume the execution of suspended
+ *
+ * The coroutine is started directly in the invoker's thread without going through the [ContinuationInterceptor] that might
+ * be present in the completion's [CoroutineContext]. It is invoker's responsibility to ensure that the proper invocation
+ * context is established.
+ *
+ * This function is designed to be used from inside of [suspendCoroutineUninterceptedOrReturn] to resume the execution of suspended
  * coroutine using a reference to the suspending function.
  */
 @Suppress("UNCHECKED_CAST")

runtime/src/main/kotlin/kotlin/io/Console.kt

@@ -14,23 +14,23 @@ public actual fun print(message: Any?) {
     print(message.toString())
 }
 
-/** Prints the given [message] and newline to the standard output stream. */
+/** Prints the given [message] and the line separator to the standard output stream. */
 @SymbolName("Kotlin_io_Console_println")
 external public fun println(message: String)
 
-/** Prints the given [message] and newline to the standard output stream. */
+/** Prints the given [message] and the line separator to the standard output stream. */
 public actual fun println(message: Any?) {
     println(message.toString())
 }
 
-/** Prints newline to the standard output stream. */
+/** Prints the line separator to the standard output stream. */
 @SymbolName("Kotlin_io_Console_println0")
 external public actual fun println()
 
 /**
  * Reads a line of input from the standard input stream.
  *
- * @return the line read or `null` if the input is empty.
+ * @return the line read or `null` if the input stream is redirected to a file and the end of file has been reached.
  */
 @SymbolName("Kotlin_io_Console_readLine")
 external public fun readLine(): String?

runtime/src/main/kotlin/kotlin/math/math.kt

@@ -201,14 +201,14 @@ external public actual fun exp(x: Double): Double
 /**
  * Computes `exp(x) - 1`.
  *
- * This actual function can be implemented to produce more precise result for [x] near zero.
+ * This function can be implemented to produce more precise result for [x] near zero.
  *
  * Special cases:
  *   - `expm1(NaN)` is `NaN`
  *   - `expm1(+Inf)` is `+Inf`
  *   - `expm1(-Inf)` is `-1.0`
  *
- * @see [exp] actual function.
+ * @see [exp] function.
  */
 @SinceKotlin("1.2")
 @SymbolName("Kotlin_math_expm1")
@@ -224,7 +224,7 @@ external public actual fun expm1(x: Double): Double
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
  *
- * See also logarithm actual functions for common fixed bases: [ln], [log10] and [log2].
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public actual fun log(x: Double, base: Double): Double {
@@ -266,7 +266,7 @@ external public actual fun log2(x: Double): Double
 /**
  * Computes `ln(x + 1)`.
  *
- * This actual function can be implemented to produce more precise result for [x] near zero.
+ * This function can be implemented to produce more precise result for [x] near zero.
  *
  * Special cases:
  *   - `ln1p(NaN)` is `NaN`
@@ -274,8 +274,8 @@ external public actual fun log2(x: Double): Double
  *   - `ln1p(-1.0)` is `-Inf`
  *   - `ln1p(+Inf)` is `+Inf`
  *
- * @see [ln] actual function
+ * @see [ln] function
- * @see [expm1] actual function
+ * @see [expm1] function
  */
 @SinceKotlin("1.2")
 @SymbolName("Kotlin_math_ln1p")
@@ -750,14 +750,14 @@ external public actual fun exp(x: Float): Float
 /**
  * Computes `exp(x) - 1`.
  *
- * This actual function can be implemented to produce more precise result for [x] near zero.
+ * This function can be implemented to produce more precise result for [x] near zero.
  *
  * Special cases:
  *   - `expm1(NaN)` is `NaN`
  *   - `expm1(+Inf)` is `+Inf`
  *   - `expm1(-Inf)` is `-1.0`
  *
- * @see [exp] actual function.
+ * @see [exp] function.
  */
 @SinceKotlin("1.2")
 @SymbolName("Kotlin_math_expm1f")
@@ -773,7 +773,7 @@ external public actual fun expm1(x: Float): Float
  *   - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
  *   - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
  *
- * See also logarithm actual functions for common fixed bases: [ln], [log10] and [log2].
+ * See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
  */
 @SinceKotlin("1.2")
 public actual fun log(x: Float, base: Float): Float {
@@ -815,7 +815,7 @@ external public actual fun log2(x: Float): Float
 /**
  * Computes `ln(a + 1)`.
  *
- * This actual function can be implemented to produce more precise result for [x] near zero.
+ * This function can be implemented to produce more precise result for [x] near zero.
  *
  * Special cases:
  *   - `ln1p(NaN)` is `NaN`
@@ -823,8 +823,8 @@ external public actual fun log2(x: Float): Float
  *   - `ln1p(-1.0)` is `-Inf`
  *   - `ln1p(+Inf)` is `+Inf`
  *
- * @see [ln] actual function
+ * @see [ln] function
- * @see [expm1] actual function
+ * @see [expm1] function
  */
 @SinceKotlin("1.2")
 @SymbolName("Kotlin_math_ln1pf")

runtime/src/main/kotlin/kotlin/native/internal/Strings.kt

@@ -84,7 +84,7 @@ public actual fun String.replaceFirst(oldValue: String, newValue: String, ignore
  * Returns a copy of this string having its first letter lowercased, or the original string,
  * if it's empty or already starts with a lower case letter.
  *
- * @sample samples.text.Strings.decaptialize
+ * @sample samples.text.Strings.decapitalize
  */
 public actual fun String.decapitalize(): String {
     return if (isNotEmpty() && this[0].isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this
@@ -106,9 +106,7 @@ public actual inline fun String.substring(startIndex: Int, endIndex: Int): Strin
         subSequence(startIndex, endIndex) as String
 
 /**
- * Returns the substring of this string starting at the [startIndex].
+ * Returns a substring of this string that starts at the specified [startIndex] and continues to the end of the string.
- *
- * @param startIndex the start index (inclusive).
  */
 @kotlin.internal.InlineOnly
 public actual inline fun String.substring(startIndex: Int): String =
@@ -171,7 +169,7 @@ external public actual fun String.toUpperCase(): String
 external public actual inline fun String.toLowerCase(): String
 
 /**
- * Returns an array containing all characters of the specified string.
+ * Returns a new character array containing the characters from this string.
  */
 @SymbolName("Kotlin_String_toCharArray")
 external public fun String.toCharArray() : CharArray
@@ -180,7 +178,7 @@ external public fun String.toCharArray() : CharArray
  * Returns a copy of this string having its first letter uppercased, or the original string,
  * if it's empty or already starts with an upper case letter.
  *
- * @sample samples.text.Strings.captialize
+ * @sample samples.text.Strings.capitalize
  */
 public actual fun String.capitalize(): String {
     return if (isNotEmpty() && this[0].isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this

runtime/src/main/kotlin/kotlin/ranges/Ranges.kt

@@ -114,7 +114,7 @@ private class ClosedFloatRange (
 }
 
 /**
- * Creates a range from this [Float] value to the specified [other] value.
+ * Creates a range from this [Float] value to the specified [that] value.
  *
  * Numbers are compared with the ends of this range according to IEEE-754.
  */

runtime/src/main/kotlin/kotlin/text/Regex.kt

@@ -28,6 +28,7 @@ actual public enum class RegexOption(override val value: Int, override val mask:
 
     /**
      * Enables multiline mode.
+     *
      * In multiline mode the expressions `^` and `$` match just after or just before,
      * respectively, a line terminator or the end of the input sequence.
      */
@@ -35,6 +36,7 @@ actual public enum class RegexOption(override val value: Int, override val mask:
 
     /**
      * Enables literal parsing of the pattern.
+     *
      * Metacharacters or escape sequences in the input sequence will be given no special meaning.
      */
     LITERAL(Pattern.LITERAL),
@@ -64,9 +66,8 @@ actual public enum class RegexOption(override val value: Int, override val mask:
 actual data class MatchGroup(actual val value: String, val range: IntRange)
 
 /**
- * Represents an immutable regular expression.
+ * Represents a compiled regular expression.
- *
+ * Provides functions to match strings in text with a pattern, replace the found occurrences and split text around matches.
- * For pattern syntax reference see [Pattern]
  */
 actual public class Regex internal constructor(internal val nativePattern: Pattern) {
 
@@ -94,15 +95,21 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
     actual val options: Set<RegexOption> = fromInt(nativePattern.flags)
 
     actual companion object {
-        /** Returns a literal regex for the specified [literal] string. */
+        /**
+         * Returns a regular expression that matches the specified [literal] string literally.
+         * No characters of that string will have special meaning when searching for an occurrence of the regular expression.
+         */
         actual fun fromLiteral(literal: String): Regex = Regex(literal, RegexOption.LITERAL)
 
-        /** Returns a literal pattern for the specified [literal] string. */
+        /**
+         * Returns a regular expression pattern string that matches the specified [literal] string literally.
+         * No characters of that string will have special meaning when searching for an occurrence of the regular expression.
+         */
         actual fun escape(literal: String): String = Pattern.quote(literal)
 
         /**
-         * Returns a replacement string for the given one that has all backslashes
+         * Returns a literal replacement expression for the specified [literal] string.
-         * and dollar signs escaped.
+         * No characters of that string will have special meaning when it is used as a replacement string in [Regex.replace] function.
          */
         actual fun escapeReplacement(literal: String): String {
             if (!literal.contains('\\') && !literal.contains('$'))
@@ -248,7 +255,7 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
     /**
      * Replaces the first occurrence of this regular expression in the specified [input] string with specified [replacement] expression.
      *
-     * @param replacement A replacement expression that can include substitutions. See [Matcher.appendReplacement] for details.
+     * @param replacement A replacement expression that can include substitutions.
      */
     actual fun replaceFirst(input: CharSequence, replacement: String): String
             = replaceFirst(input) { match -> processReplacement(match, replacement) }
@@ -282,7 +289,12 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
         return result
     }
 
-    /** Returns the string representation of this regular expression, namely the [pattern] of this regular expression. */
+    /**
+     * Returns the string representation of this regular expression, namely the [pattern] of this regular expression.
+     *
+     * Note that another regular expression constructed from the same pattern string may have different [options]
+     * and may match strings differently.
+     */
     override fun toString(): String = nativePattern.toString()
 
     // Native specific =================================================================================================
@@ -291,7 +303,11 @@ actual public class Regex internal constructor(internal val nativePattern: Patte
     /** Indicates whether the regular expression can find at least one match in the specified [input] starting with [index]. */
     fun containsMatchIn(input: CharSequence, index: Int): Boolean = find(input, index) != null
 
-    /** Replaces the first occurrence of this regular expression in the specified [input] string with specified using specified transfromation */
+    /**
+     * Replaces the first occurrence of this regular expression in the specified [input] string with the result of calling
+     * the given function [transform] that takes a [MatchResult] representing the occurrence and returns a string to be used as a
+     * replacement for that occurrence.
+     */
     fun replaceFirst(input: CharSequence, transform: (MatchResult) -> CharSequence): String {
         val match = find(input) ?: return input.toString()
         val length = input.length

runtime/src/main/kotlin/kotlin/text/StringNumberConversions.kt

@@ -9,6 +9,8 @@ import kotlin.native.internal.FloatingPointParser
 
 /**
  * Returns a string representation of this [Byte] value in the specified [radix].
+ *
+ * @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -16,6 +18,8 @@ public actual inline fun Byte.toString(radix: Int): String = this.toInt().toStri
 
 /**
  * Returns a string representation of this [Short] value in the specified [radix].
+ *
+ * @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -27,6 +31,8 @@ external internal fun intToString(value: Int, radix: Int): String
 
 /**
  * Returns a string representation of this [Int] value in the specified [radix].
+ *
+ * @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -38,6 +44,8 @@ external internal fun longToString(value: Long, radix: Int): String
 
 /**
  * Returns a string representation of this [Long] value in the specified [radix].
+ *
+ * @throws IllegalArgumentException when [radix] is not a valid radix for number to string conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -59,6 +67,7 @@ public actual inline fun String.toByte(): Byte = toByteOrNull() ?: throw NumberF
 /**
  * Parses the string as a signed [Byte] number and returns the result.
  * @throws NumberFormatException if the string is not a valid representation of a number.
+ * @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -74,6 +83,7 @@ public actual inline fun String.toShort(): Short = toShortOrNull() ?: throw Numb
 /**
  * Parses the string as a [Short] number and returns the result.
  * @throws NumberFormatException if the string is not a valid representation of a number.
+ * @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -89,6 +99,7 @@ public actual inline fun String.toInt(): Int = toIntOrNull() ?: throw NumberForm
 /**
  * Parses the string as an [Int] number and returns the result.
  * @throws NumberFormatException if the string is not a valid representation of a number.
+ * @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly
@@ -104,6 +115,7 @@ public actual inline fun String.toLong(): Long = toLongOrNull() ?: throw NumberF
 /**
  * Parses the string as a [Long] number and returns the result.
  * @throws NumberFormatException if the string is not a valid representation of a number.
+ * @throws IllegalArgumentException when [radix] is not a valid radix for string to number conversion.
  */
 @SinceKotlin("1.1")
 @kotlin.internal.InlineOnly