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

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

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