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

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)`.