Document order of array elements initialization (KT-32353)

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