KT-22298 Improve docs for Array.copyOf(newSize: Int)

Signed-off-by: Valeriy Zhirnov <neonailol@gmail.com>

libraries/stdlib/common/src/generated/_Arrays.kt

@@ -5574,92 +5574,164 @@ public expect fun CharArray.contentToString(): String
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("NO_ACTUAL_FOR_EXPECT")
 public expect fun <T> Array<T>.copyOf(): Array<T>
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun ByteArray.copyOf(): ByteArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun ShortArray.copyOf(): ShortArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun IntArray.copyOf(): IntArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun LongArray.copyOf(): LongArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun FloatArray.copyOf(): FloatArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun DoubleArray.copyOf(): DoubleArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun BooleanArray.copyOf(): BooleanArray
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public expect fun CharArray.copyOf(): CharArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun ByteArray.copyOf(newSize: Int): ByteArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun ShortArray.copyOf(newSize: Int): ShortArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun IntArray.copyOf(newSize: Int): IntArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun LongArray.copyOf(newSize: Int): LongArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun FloatArray.copyOf(newSize: Int): FloatArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun DoubleArray.copyOf(newSize: Int): DoubleArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun BooleanArray.copyOf(newSize: Int): BooleanArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public expect fun CharArray.copyOf(newSize: Int): CharArray
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with null values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain null values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizingCopyOf
  */
 @Suppress("NO_ACTUAL_FOR_EXPECT")
 public expect fun <T> Array<T>.copyOf(newSize: Int): Array<T?>

libraries/stdlib/js/src/generated/_ArraysJs.kt

@@ -409,6 +409,8 @@ public actual fun CharArray.contentToString(): String {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("ACTUAL_WITHOUT_EXPECT", "NOTHING_TO_INLINE")
 public actual inline fun <T> Array<out T>.copyOf(): Array<T> {
@@ -417,6 +419,8 @@ public actual inline fun <T> Array<out T>.copyOf(): Array<T> {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("NOTHING_TO_INLINE")
 public actual inline fun ByteArray.copyOf(): ByteArray {
@@ -425,6 +429,8 @@ public actual inline fun ByteArray.copyOf(): ByteArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("NOTHING_TO_INLINE")
 public actual inline fun ShortArray.copyOf(): ShortArray {
@@ -433,6 +439,8 @@ public actual inline fun ShortArray.copyOf(): ShortArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("NOTHING_TO_INLINE")
 public actual inline fun IntArray.copyOf(): IntArray {
@@ -441,6 +449,8 @@ public actual inline fun IntArray.copyOf(): IntArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public actual fun LongArray.copyOf(): LongArray {
     return withType("LongArray", this.asDynamic().slice())
@@ -448,6 +458,8 @@ public actual fun LongArray.copyOf(): LongArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("NOTHING_TO_INLINE")
 public actual inline fun FloatArray.copyOf(): FloatArray {
@@ -456,6 +468,8 @@ public actual inline fun FloatArray.copyOf(): FloatArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @Suppress("NOTHING_TO_INLINE")
 public actual inline fun DoubleArray.copyOf(): DoubleArray {
@@ -464,6 +478,8 @@ public actual inline fun DoubleArray.copyOf(): DoubleArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public actual fun BooleanArray.copyOf(): BooleanArray {
     return withType("BooleanArray", this.asDynamic().slice())
@@ -471,69 +487,125 @@ public actual fun BooleanArray.copyOf(): BooleanArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 public actual fun CharArray.copyOf(): CharArray {
     return withType("CharArray", this.asDynamic().slice())
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun ByteArray.copyOf(newSize: Int): ByteArray {
     return fillFrom(this, ByteArray(newSize))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun ShortArray.copyOf(newSize: Int): ShortArray {
     return fillFrom(this, ShortArray(newSize))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun IntArray.copyOf(newSize: Int): IntArray {
     return fillFrom(this, IntArray(newSize))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun LongArray.copyOf(newSize: Int): LongArray {
     return withType("LongArray", arrayCopyResize(this, newSize, 0L))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun FloatArray.copyOf(newSize: Int): FloatArray {
     return fillFrom(this, FloatArray(newSize))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun DoubleArray.copyOf(newSize: Int): DoubleArray {
     return fillFrom(this, DoubleArray(newSize))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun BooleanArray.copyOf(newSize: Int): BooleanArray {
     return withType("BooleanArray", arrayCopyResize(this, newSize, false))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 public actual fun CharArray.copyOf(newSize: Int): CharArray {
     return withType("CharArray", fillFrom(this, CharArray(newSize)))
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with null values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain null values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizingCopyOf
  */
 @Suppress("ACTUAL_WITHOUT_EXPECT")
 public actual fun <T> Array<out T>.copyOf(newSize: Int): Array<T?> {

libraries/stdlib/jvm/src/generated/_ArraysJvm.kt

@@ -599,6 +599,8 @@ public actual inline fun CharArray.contentToString(): String {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun <T> Array<T>.copyOf(): Array<T> {
@@ -607,6 +609,8 @@ public actual inline fun <T> Array<T>.copyOf(): Array<T> {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ByteArray.copyOf(): ByteArray {
@@ -615,6 +619,8 @@ public actual inline fun ByteArray.copyOf(): ByteArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ShortArray.copyOf(): ShortArray {
@@ -623,6 +629,8 @@ public actual inline fun ShortArray.copyOf(): ShortArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun IntArray.copyOf(): IntArray {
@@ -631,6 +639,8 @@ public actual inline fun IntArray.copyOf(): IntArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun LongArray.copyOf(): LongArray {
@@ -639,6 +649,8 @@ public actual inline fun LongArray.copyOf(): LongArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun FloatArray.copyOf(): FloatArray {
@@ -647,6 +659,8 @@ public actual inline fun FloatArray.copyOf(): FloatArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun DoubleArray.copyOf(): DoubleArray {
@@ -655,6 +669,8 @@ public actual inline fun DoubleArray.copyOf(): DoubleArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun BooleanArray.copyOf(): BooleanArray {
@@ -663,6 +679,8 @@ public actual inline fun BooleanArray.copyOf(): BooleanArray {
 
 /**
  * Returns new array which is a copy of the original array.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.copyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun CharArray.copyOf(): CharArray {
@@ -670,7 +688,13 @@ public actual inline fun CharArray.copyOf(): CharArray {
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ByteArray.copyOf(newSize: Int): ByteArray {
@@ -678,7 +702,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun ShortArray.copyOf(newSize: Int): ShortArray {
@@ -686,7 +716,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun IntArray.copyOf(newSize: Int): IntArray {
@@ -694,7 +730,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun LongArray.copyOf(newSize: Int): LongArray {
@@ -702,7 +744,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun FloatArray.copyOf(newSize: Int): FloatArray {
@@ -710,7 +758,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun DoubleArray.copyOf(newSize: Int): DoubleArray {
@@ -718,7 +772,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun BooleanArray.copyOf(newSize: Int): BooleanArray {
@@ -726,7 +786,13 @@ 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].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with primitive default values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain primitive default values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun CharArray.copyOf(newSize: Int): CharArray {
@@ -734,7 +800,13 @@ public actual inline fun CharArray.copyOf(newSize: Int): CharArray {
 }
 
 /**
- * Returns new array which is a copy of the original array, resized to the given [newSize].
+ * Returns new array which is a copy of the original array, resized to the given [newSize],
+ * truncating original values or padding new array with null values if necessary.
+ * 
+ * For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+ * For all indices that are valid in the copy, but not in the original, the copy will contain null values.
+ * 
+ * @sample samples.collections.Arrays.CopyOfOperations.resizingCopyOf
  */
 @kotlin.internal.InlineOnly
 public actual inline fun <T> Array<T>.copyOf(newSize: Int): Array<T?> {

libraries/stdlib/samples/test/samples/collections/arrays.kt

@@ -17,7 +17,6 @@
 package samples.collections
 
 import samples.*
-import kotlin.test.*
 
 
 @RunWith(Enclosed::class)
@@ -76,4 +75,32 @@ class Arrays {
         }
     }
 
+    class CopyOfOperations {
+
+        @Sample
+        fun copyOf() {
+            val array = arrayOf("apples", "oranges", "limes")
+            val arrayCopy = array.copyOf()
+            assertPrints(arrayCopy.contentToString(), "[apples, oranges, limes]")
+        }
+
+        @Sample
+        fun resizingCopyOf() {
+            val array = arrayOf("apples", "oranges", "limes")
+            val arrayCopyPadded = array.copyOf(5)
+            assertPrints(arrayCopyPadded.contentToString(), "[apples, oranges, limes, null, null]")
+            val arrayCopyTruncated = array.copyOf(2)
+            assertPrints(arrayCopyTruncated.contentToString(), "[apples, oranges]")
+        }
+
+        @Sample
+        fun resizedPrimitiveCopyOf() {
+            val array = intArrayOf(1, 2, 3)
+            val arrayCopyPadded = array.copyOf(5)
+            assertPrints(arrayCopyPadded.contentToString(), "[1, 2, 3, 0, 0]")
+            val arrayCopyTruncated = array.copyOf(2)
+            assertPrints(arrayCopyTruncated.contentToString(), "[1, 2]")
+        }
+    }
+
 }

libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt

@@ -408,6 +408,7 @@ object ArrayOps : TemplateGroupBase() {
         include(ArraysOfPrimitives, PrimitiveType.defaultPrimitives)
     } builder {
         doc { "Returns new array which is a copy of the original array." }
+        sample("samples.collections.Arrays.CopyOfOperations.copyOf")
         returns("SELF")
         on(Platform.JVM) {
             inlineOnly()
@@ -443,8 +444,17 @@ object ArrayOps : TemplateGroupBase() {
         include(ArraysOfPrimitives, PrimitiveType.defaultPrimitives)
         include(InvariantArraysOfObjects)
     } builder {
-        doc { "Returns new array which is a copy of the original array, resized to the given [newSize]." }
+        doc {
+            """
+            Returns new array which is a copy of the original array, resized to the given [newSize],
+            truncating original values or padding new array with ${if(family == ArraysOfPrimitives) "primitive default" else "null"} values if necessary.
+
+            For all indices that are valid in both the original array and the copy, the two arrays contents will be identical.
+            For all indices that are valid in the copy, but not in the original, the copy will contain ${if(family == ArraysOfPrimitives) "primitive default" else "null"} values.
+            """
+        }
         specialFor(ArraysOfPrimitives) {
+            sample("samples.collections.Arrays.CopyOfOperations.resizedPrimitiveCopyOf")
             returns("SELF")
             on(Platform.JS) {
                 when (primitive!!) {
@@ -461,6 +471,7 @@ object ArrayOps : TemplateGroupBase() {
 
         }
         specialFor(InvariantArraysOfObjects) {
+            sample("samples.collections.Arrays.CopyOfOperations.resizingCopyOf")
             returns("Array<T?>")
             on(Platform.JS) {
                 family = ArraysOfObjects