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)
 

generators/builtins/arrays.kt

@@ -39,7 +39,10 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             out.println("public class ${s}Array(size: Int) {")
             out.println("    /**")
             out.println("     * Creates a new array of the specified [size], where each element is calculated by calling the specified")
-            out.println("     * [init] function. The [init] function returns an array element given its index.")
+            out.println("     * [init] function.")
+            out.println("     *")
+            out.println("     * The function [init] is called for each array element sequentially starting from the first one.")
+            out.println("     * It should return the value for an array element given its index.")
             out.println("     */")
             out.println("    public inline constructor(size: Int, init: (Int) -> $s)")
             out.println()

generators/builtins/unsignedTypes.kt

@@ -476,6 +476,13 @@ class UnsignedArrayGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIn
 
         // TODO: Make inline constructor, like in ByteArray
         out.println("""
+/**
+ * Creates a new array of the specified [size], where each element is calculated by calling the specified
+ * [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.
+ */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
 @kotlin.internal.InlineOnly

libraries/stdlib/js-ir/builtins/Arrays.kt

@@ -20,7 +20,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)
 
@@ -43,7 +46,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)
 
@@ -66,7 +72,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)
 
@@ -89,7 +98,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)
 
@@ -112,7 +124,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)
 
@@ -135,7 +150,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)
 
@@ -158,7 +176,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)
 
@@ -181,7 +202,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)
 

libraries/stdlib/src/kotlin/collections/Collections.kt

@@ -125,7 +125,11 @@ public fun <T : Any> listOfNotNull(vararg elements: T?): List<T> = elements.filt
 
 /**
  * Creates a new read-only list with the specified [size], where each element is calculated by calling the specified
- * [init] function. The [init] function returns a list element given its index.
+ * [init] function.
+ *
+ * The function [init] is called for each list element sequentially starting from the first one.
+ * It should return the value for a list element given its index.
+ *
  * @sample samples.collections.Collections.Lists.readOnlyListFromInitializer
  */
 @SinceKotlin("1.1")
@@ -134,7 +138,11 @@ public inline fun <T> List(size: Int, init: (index: Int) -> T): List<T> = Mutabl
 
 /**
  * Creates a new mutable list with the specified [size], where each element is calculated by calling the specified
- * [init] function. The [init] function returns a list element given its index.
+ * [init] function.
+ *
+ * The function [init] is called for each list element sequentially starting from the first one.
+ * It should return the value for a list element given its index.
+ *
  * @sample samples.collections.Collections.Lists.mutableListFromInitializer
  */
 @SinceKotlin("1.1")

libraries/stdlib/unsigned/src/kotlin/UByteArray.kt

@@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: ByteArray) : Collection
     override fun isEmpty(): Boolean = this.storage.size == 0
 }
 
+/**
+ * Creates a new array of the specified [size], where each element is calculated by calling the specified
+ * [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.
+ */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
 @kotlin.internal.InlineOnly

libraries/stdlib/unsigned/src/kotlin/UIntArray.kt

@@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: IntArray) : Collection<
     override fun isEmpty(): Boolean = this.storage.size == 0
 }
 
+/**
+ * Creates a new array of the specified [size], where each element is calculated by calling the specified
+ * [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.
+ */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
 @kotlin.internal.InlineOnly

libraries/stdlib/unsigned/src/kotlin/ULongArray.kt

@@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: LongArray) : Collection
     override fun isEmpty(): Boolean = this.storage.size == 0
 }
 
+/**
+ * Creates a new array of the specified [size], where each element is calculated by calling the specified
+ * [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.
+ */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
 @kotlin.internal.InlineOnly

libraries/stdlib/unsigned/src/kotlin/UShortArray.kt

@@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: ShortArray) : Collectio
     override fun isEmpty(): Boolean = this.storage.size == 0
 }
 
+/**
+ * Creates a new array of the specified [size], where each element is calculated by calling the specified
+ * [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.
+ */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
 @kotlin.internal.InlineOnly