Document order of array elements initialization (KT-32353)

core/builtins/native/kotlin/Array.kt

@@ -15,7 +15,10 @@ package kotlin
 public 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.
      */
     public inline constructor(size: Int, init: (Int) -> T)
 

core/builtins/native/kotlin/Arrays.kt

@@ -14,7 +14,10 @@ package kotlin
 public class ByteArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Byte)
 
@@ -48,7 +51,10 @@ public class ByteArray(size: Int) {
 public class CharArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Char)
 
@@ -82,7 +88,10 @@ public class CharArray(size: Int) {
 public class ShortArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Short)
 
@@ -116,7 +125,10 @@ public class ShortArray(size: Int) {
 public class IntArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Int)
 
@@ -150,7 +162,10 @@ public class IntArray(size: Int) {
 public class LongArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Long)
 
@@ -184,7 +199,10 @@ public class LongArray(size: Int) {
 public class FloatArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Float)
 
@@ -218,7 +236,10 @@ public class FloatArray(size: Int) {
 public class DoubleArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Double)
 
@@ -252,7 +273,10 @@ public class DoubleArray(size: Int) {
 public class BooleanArray(size: Int) {
     /**
      * 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.
      */
     public inline constructor(size: Int, init: (Int) -> Boolean)