Improve Array contentEquals and contentDeepEquals doc #KT-66896

Author: Abduqodiri Qurbonzoda

kotlin-native/runtime/src/main/kotlin/generated/_ArraysNative.kt

@@ -126,8 +126,14 @@ public actual fun UShortArray.asList(): List<UShort> {
 }
 
 /**
- * Returns `true` if the two specified arrays are *structurally* equal to one another,
- * i.e. contain the same number of the same elements in the same order.
+ * Checks if the two specified arrays are *structurally* equal to one another.
+ * 
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * 
+ * @param other the array to compare with this array.
+ * @return `true` if the two arrays are structurally equal, `false` otherwise.
+ * 
+ * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals
  */
 @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.")
 @SinceKotlin("1.3")
@@ -138,8 +144,14 @@ public infix fun UIntArray.contentEquals(other: UIntArray): Boolean {
 }
 
 /**
- * Returns `true` if the two specified arrays are *structurally* equal to one another,
- * i.e. contain the same number of the same elements in the same order.
+ * Checks if the two specified arrays are *structurally* equal to one another.
+ * 
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * 
+ * @param other the array to compare with this array.
+ * @return `true` if the two arrays are structurally equal, `false` otherwise.
+ * 
+ * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals
  */
 @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.")
 @SinceKotlin("1.3")
@@ -150,8 +162,14 @@ public infix fun ULongArray.contentEquals(other: ULongArray): Boolean {
 }
 
 /**
- * Returns `true` if the two specified arrays are *structurally* equal to one another,
- * i.e. contain the same number of the same elements in the same order.
+ * Checks if the two specified arrays are *structurally* equal to one another.
+ * 
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * 
+ * @param other the array to compare with this array.
+ * @return `true` if the two arrays are structurally equal, `false` otherwise.
+ * 
+ * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals
  */
 @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.")
 @SinceKotlin("1.3")
@@ -162,8 +180,14 @@ public infix fun UByteArray.contentEquals(other: UByteArray): Boolean {
 }
 
 /**
- * Returns `true` if the two specified arrays are *structurally* equal to one another,
- * i.e. contain the same number of the same elements in the same order.
+ * Checks if the two specified arrays are *structurally* equal to one another.
+ * 
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * 
+ * @param other the array to compare with this array.
+ * @return `true` if the two arrays are structurally equal, `false` otherwise.
+ * 
+ * @sample samples.collections.Arrays.ContentOperations.intArrayContentEquals
  */
 @Deprecated("Use Kotlin compiler 1.4 to avoid deprecation warning.")
 @SinceKotlin("1.3")

kotlin-native/runtime/src/main/kotlin/generated/_UArraysNative.kt

@@ -354,11 +354,14 @@ public fun assertContains(charSequence: CharSequence, regex: Regex, message: Str
 }
 
 /**
- * Asserts that the [expected] iterable is *structurally* equal to the [actual] iterable,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] iterable is *structurally* equal to the [actual] iterable, with an optional [message].
  *
- * The elements are compared for equality with the [equals][Any.equals] function.
- * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ * Two iterables are considered structurally equal if they have the same size,
+ * and elements at corresponding positions, following the iteration order, are equal.
+ * Elements are compared for equality using the [equals][Any.equals] function.
+ * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ *
+ * The iterables are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun <@OnlyInputTypes T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null) {
@@ -374,110 +377,140 @@ public fun <@OnlyInputTypes T> assertContentEquals(expected: Set<T>?, actual: Se
     assertContentEquals(expected, actual?.asIterable(), message)
 
 /**
- * Asserts that the [expected] sequence is *structurally* equal to the [actual] sequence,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] sequence is *structurally* equal to the [actual] sequence, with an optional [message].
+ *
+ * Two sequences are considered structurally equal if they have the same size,
+ * and elements at corresponding positions, following the iteration order, are equal.
+ * Elements are compared for equality using the [equals][Any.equals] function.
+ * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
  *
- * The elements are compared for equality with the [equals][Any.equals] function.
- * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ * The sequences are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun <@OnlyInputTypes T> assertContentEquals(expected: Sequence<T>?, actual: Sequence<T>?, message: String? = null) {
     assertIterableContentEquals("Sequence", message, expected, actual, Sequence<*>::iterator)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
  *
- * The elements are compared for equality with the [equals][Any.equals] function.
- * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * Elements are compared for equality using the [equals][Any.equals] function.
+ * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun <@OnlyInputTypes T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, Array<*>::get, Array<*>?::contentToString, Array<*>?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: ByteArray?, actual: ByteArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, ByteArray::get, ByteArray?::contentToString, ByteArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: ShortArray?, actual: ShortArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, ShortArray::get, ShortArray?::contentToString, ShortArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: IntArray?, actual: IntArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, IntArray::get, IntArray?::contentToString, IntArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: LongArray?, actual: LongArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, LongArray::get, LongArray?::contentToString, LongArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * Elements are compared for equality using the [equals][Any.equals] function.
+ * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
  *
- * The elements are compared for equality with the [equals][Any.equals] function.
- * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: FloatArray?, actual: FloatArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, FloatArray::get, FloatArray?::contentToString, FloatArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ * Elements are compared for equality using the [equals][Any.equals] function.
+ * For floating point numbers, this means `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
  *
- * The elements are compared for equality with the [equals][Any.equals] function.
- * For floating point numbers it means that `NaN` is equal to itself and `-0.0` is not equal to `0.0`.
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: DoubleArray?, actual: DoubleArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, DoubleArray::get, DoubleArray?::contentToString, DoubleArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: BooleanArray?, actual: BooleanArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, BooleanArray::get, BooleanArray?::contentToString, BooleanArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 public fun assertContentEquals(expected: CharArray?, actual: CharArray?, message: String? = null) {
     assertArrayContentEquals(message, expected, actual, { it.size }, CharArray::get, CharArray?::contentToString, CharArray?::contentEquals)
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 @OptIn(ExperimentalUnsignedTypes::class)
@@ -486,8 +519,11 @@ public fun assertContentEquals(expected: UByteArray?, actual: UByteArray?, messa
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 @OptIn(ExperimentalUnsignedTypes::class)
@@ -496,8 +532,11 @@ public fun assertContentEquals(expected: UShortArray?, actual: UShortArray?, mes
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 @OptIn(ExperimentalUnsignedTypes::class)
@@ -506,8 +545,11 @@ public fun assertContentEquals(expected: UIntArray?, actual: UIntArray?, message
 }
 
 /**
- * Asserts that the [expected] array is *structurally* equal to the [actual] array,
- * i.e. contains the same number of the same elements in the same order, with an optional [message].
+ * Asserts that the [expected] array is *structurally* equal to the [actual] array, with an optional [message].
+ *
+ * Two arrays are considered structurally equal if they have the same size, and elements at corresponding indices are equal.
+ *
+ * The arrays are also considered equal if both are `null`.
  */
 @SinceKotlin("1.5")
 @OptIn(ExperimentalUnsignedTypes::class)