docs: added KDoc for Comparator, fixed KDoc for comparison binarySearch()

libraries/stdlib/common/src/kotlin/KotlinH.kt

@@ -9,11 +9,28 @@ import kotlin.annotation.AnnotationTarget.FIELD
 import kotlin.annotation.AnnotationTarget.PROPERTY
 
 
-
+/**
+ * Provides a comparison function for imposing a total ordering between instances of the type [T].
+ */
 expect interface Comparator<T> {
+    /**
+     * Compares its two arguments for order. Returns zero if the arguments are equal,
+     * a negative number if the first argument is less than the second, or a positive number
+     * if the first argument is greater than the second.
+     */
     fun compare(a: T, b: T): Int
 }
 
+/**
+ * Creates a [Comparator] with the provided [comparison] function.
+ *
+ * @param comparison function that compares its two arguments for order.
+ * Must return zero if the arguments are equal, a negative number
+ * if the first argument is less than the second, or a positive number
+ * if the first argument is greater than the second.
+ *
+ * @return [Comparator] object with the provided implementation of the comparison function.
+ */
 // TODO: Satisfied with SAM-constructor for Comparator interface in JVM
 @Suppress("NO_ACTUAL_FOR_EXPECT")
 expect inline fun <T> Comparator(crossinline comparison: (a: T, b: T) -> Int): Comparator<T>

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

@@ -334,13 +334,17 @@ public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(
 
 
 /**
- * Searches this list or its range for an element for which [comparison] function returns zero using the binary search algorithm.
- * The list is expected to be sorted into ascending order according to the provided [comparison],
- * otherwise the result is undefined.
+ * Searches this list or its range for an element for which the given [comparison] function returns zero using the binary search algorithm.
+ *
+ * The list is expected to be sorted so that the signs of the [comparison] function's return values ascend on the list elements,
+ * i.e. negative values come before zero and zeroes come before positive values.
+ * Otherwise, the result is undefined.
  *
  * If the list contains multiple elements for which [comparison] returns zero, there is no guarantee which one will be found.
  *
- * @param comparison function that compares an element of the list with the element being searched.
+ * @param comparison function that returns zero when called on the list element being searched.
+ * On the elements coming before the target element, the function must return negative values;
+ * on the elements coming after the target element, the function must return positive values.
  *
  * @return the index of the found element, if it is contained in the list within the specified range;
  * otherwise, the inverted insertion point `(-insertion point - 1)`.