Improve the documentation of binarySearch functions.

#KT-10198 Fixed

libraries/stdlib/src/generated/_Arrays.kt

@@ -11895,7 +11895,13 @@ public fun CharArray.asList(): List<Char> {
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted according to the specified [comparator].
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted according to the specified [comparator], otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted according to the specified [comparator].
  */
 @kotlin.jvm.JvmVersion
 public fun <T> Array<out T>.binarySearch(element: T, comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11903,7 +11909,13 @@ public fun <T> Array<out T>.binarySearch(element: T, comparator: Comparator<in T
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun <T> Array<out T>.binarySearch(element: T, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11911,7 +11923,13 @@ public fun <T> Array<out T>.binarySearch(element: T, fromIndex: Int = 0, toIndex
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun ByteArray.binarySearch(element: Byte, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11919,7 +11937,13 @@ public fun ByteArray.binarySearch(element: Byte, fromIndex: Int = 0, toIndex: In
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun ShortArray.binarySearch(element: Short, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11927,7 +11951,13 @@ public fun ShortArray.binarySearch(element: Short, fromIndex: Int = 0, toIndex:
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun IntArray.binarySearch(element: Int, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11935,7 +11965,13 @@ public fun IntArray.binarySearch(element: Int, fromIndex: Int = 0, toIndex: Int
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun LongArray.binarySearch(element: Long, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11943,7 +11979,13 @@ public fun LongArray.binarySearch(element: Long, fromIndex: Int = 0, toIndex: In
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun FloatArray.binarySearch(element: Float, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11951,7 +11993,13 @@ public fun FloatArray.binarySearch(element: Float, fromIndex: Int = 0, toIndex:
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun DoubleArray.binarySearch(element: Double, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11959,7 +12007,13 @@ public fun DoubleArray.binarySearch(element: Double, fromIndex: Int = 0, toIndex
 }
 
 /**
- * Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
+ * Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+ * The array is expected to be sorted, otherwise the result is undefined.
+ * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ * @return the index of the element, if it is contained in the array within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the array (or the specified subrange of array) still remains sorted.
  */
 @kotlin.jvm.JvmVersion
 public fun CharArray.binarySearch(element: Char, fromIndex: Int = 0, toIndex: Int = size): Int {

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

@@ -141,10 +141,18 @@ private fun <T> Array<out T>.copyToArrayOfAny(isVarargs: Boolean): Array<Any?> =
             Arrays.copyOf(this, this.size, Array<Any?>::class.java)
 
 /**
- * Searches this list or its range for the provided [element] index using binary search algorithm.
+ * Searches this list or its range for the provided [element] using the binary search algorithm.
- * The list is expected to be sorted into ascending order according to the Comparable natural ordering of its elements.
+ * The list is expected to be sorted into ascending order according to the Comparable natural ordering of its elements,
+ * otherwise the result is undefined.
  *
- * If the list contains multiple elements equal to the specified object, there is no guarantee which one will be found.
+ * If the list contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ *
+ * `null` value is considered to be less than any non-null value.
+ *
+ * @return the index of the element, if it is contained in the list within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the list (or the specified subrange of list) still remains sorted.
  */
 public fun <T: Comparable<T>> List<T?>.binarySearch(element: T?, fromIndex: Int = 0, toIndex: Int = size): Int {
     rangeCheck(size, fromIndex, toIndex)
@@ -168,10 +176,18 @@ public fun <T: Comparable<T>> List<T?>.binarySearch(element: T?, fromIndex: Int
 }
 
 /**
- * Searches this list or its range for the provided [element] index using binary search algorithm.
+ * Searches this list or its range for the provided [element] using the binary search algorithm.
- * The list is expected to be sorted into ascending order according to the specified [comparator].
+ * The list is expected to be sorted into ascending order according to the specified [comparator],
+ * otherwise the result is undefined.
  *
- * If the list contains multiple elements equal to the specified object, there is no guarantee which one will be found.
+ * If the list contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+ *
+ * `null` value is considered to be less than any non-null value.
+ *
+ * @return the index of the element, if it is contained in the list within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the list (or the specified subrange of list) still remains sorted according to the specified [comparator].
  */
 public fun <T> List<T>.binarySearch(element: T, comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Int {
     rangeCheck(size, fromIndex, toIndex)
@@ -195,10 +211,19 @@ public fun <T> List<T>.binarySearch(element: T, comparator: Comparator<in T>, fr
 }
 
 /**
- * Searches this list or its range for an index of an element with the provided [key] using binary search algorithm.
+ * Searches this list or its range for an element having the key returned by the specified [selector] function
+ * equal to the provided [key] value using the binary search algorithm.
  * The list is expected to be sorted into ascending order according to the Comparable natural ordering of keys of its elements.
+ * otherwise the result is undefined.
  *
  * If the list contains multiple elements with the specified [key], there is no guarantee which one will be found.
+ *
+ * `null` value is considered to be less than any non-null value.
+ *
+ * @return the index of the element with the specified [key], if it is contained in the list within the specified range;
+ * otherwise, the inverted insertion point `(-insertion point - 1)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the list (or the specified subrange of list) still remains sorted.
  */
 public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(key: K?, fromIndex: Int = 0, toIndex: Int = size, crossinline selector: (T) -> K?): Int =
         binarySearch(fromIndex, toIndex) { compareValues(selector(it), key) }
@@ -207,11 +232,20 @@ public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(key: K?, fromInd
 //public fun <T, K> List<T>.binarySearchBy(key: K, comparator: Comparator<K>, fromIndex: Int = 0, toIndex: Int = size(), selector: (T) -> K): Int =
 //        binarySearch(fromIndex, toIndex) { comparator.compare(selector(it), key) }
 
+
 /**
- * Searches this list or its range for an index of an element for which [comparison] function returns zero.
+ * 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].
+ * The list is expected to be sorted into ascending order according to the provided [comparison],
+ * 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.
+ *
+ * @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)`.
+ * The insertion point is defined as the index at which the element should be inserted,
+ * so that the list (or the specified subrange of list) still remains sorted.
  */
 public fun <T> List<T>.binarySearch(fromIndex: Int = 0, toIndex: Int = size, comparison: (T) -> Int): Int {
     rangeCheck(size, fromIndex, toIndex)

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

@@ -114,7 +114,19 @@ fun specialJVM(): List<GenericFunction> {
     templates add f("binarySearch(element: T, fromIndex: Int = 0, toIndex: Int = size)") {
         only(ArraysOfObjects, ArraysOfPrimitives)
         exclude(PrimitiveType.Boolean)
-        doc { "Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted." }
+        doc {
+            """
+            Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+            The array is expected to be sorted, otherwise the result is undefined.
+
+            If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+
+            @return the index of the element, if it is contained in the array within the specified range;
+            otherwise, the inverted insertion point `(-insertion point - 1)`.
+            The insertion point is defined as the index at which the element should be inserted,
+            so that the array (or the specified subrange of array) still remains sorted.
+            """
+        }
         returns("Int")
         body {
             "return Arrays.binarySearch(this, fromIndex, toIndex, element)"
@@ -123,7 +135,19 @@ fun specialJVM(): List<GenericFunction> {
 
     templates add f("binarySearch(element: T, comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size)") {
         only(ArraysOfObjects)
-        doc { "Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted according to the specified [comparator]." }
+        doc {
+            """
+            Searches the array or the range of the array for the provided [element] using the binary search algorithm.
+            The array is expected to be sorted according to the specified [comparator], otherwise the result is undefined.
+
+            If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
+
+            @return the index of the element, if it is contained in the array within the specified range;
+            otherwise, the inverted insertion point `(-insertion point - 1)`.
+            The insertion point is defined as the index at which the element should be inserted,
+            so that the array (or the specified subrange of array) still remains sorted according to the specified [comparator].
+            """
+        }
         returns("Int")
         body {
             "return Arrays.binarySearch(this, fromIndex, toIndex, element, comparator)"