From b8b8b8c84b7b3a0bd7f186e100a5ca0f652cec3a Mon Sep 17 00:00:00 2001
From: Abduqodiri Qurbonzoda <abduqodiri.qurbonzoda@jetbrains.com>
Date: Sat, 13 Jul 2019 16:54:00 +0300
Subject: [PATCH] Document order of array elements initialization (KT-32353)

---
 runtime/src/main/kotlin/kotlin/Array.kt  |  5 ++-
 runtime/src/main/kotlin/kotlin/Arrays.kt | 40 +++++++++++++++++++-----
 2 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/runtime/src/main/kotlin/kotlin/Array.kt b/runtime/src/main/kotlin/kotlin/Array.kt
index 263a79dd000..fd10e59fa88 100644
--- a/runtime/src/main/kotlin/kotlin/Array.kt
+++ b/runtime/src/main/kotlin/kotlin/Array.kt
@@ -21,7 +21,10 @@ public final class Array<T> {
 
     /**
      * Creates a new array with the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     @Suppress("TYPE_PARAMETER_AS_REIFIED")
diff --git a/runtime/src/main/kotlin/kotlin/Arrays.kt b/runtime/src/main/kotlin/kotlin/Arrays.kt
index 8f04d11a449..836c0f83473 100644
--- a/runtime/src/main/kotlin/kotlin/Arrays.kt
+++ b/runtime/src/main/kotlin/kotlin/Arrays.kt
@@ -25,7 +25,10 @@ public final class ByteArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Byte): this(size) {
@@ -86,7 +89,10 @@ public final class CharArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Char): this(size) {
@@ -148,7 +154,10 @@ public final class ShortArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Short): this(size) {
@@ -210,7 +219,10 @@ public final class IntArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Int): this(size) {
@@ -272,7 +284,10 @@ public final class LongArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Long): this(size) {
@@ -334,7 +349,10 @@ public final class FloatArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Float): this(size) {
@@ -392,7 +410,10 @@ public final class DoubleArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Double): this(size) {
@@ -450,7 +471,10 @@ public final class BooleanArray {
 
     /**
      * Creates a new array of the specified [size], where each element is calculated by calling the specified
-     * [init] function. The [init] function returns an array element given its index.
+     * [init] function.
+     *
+     * The function [init] is called for each array element sequentially starting from the first one.
+     * It should return the value for an array element given its index.
      */
     @InlineConstructor
     public constructor(size: Int, init: (Int) -> Boolean): this(size) {