classref: Sync with current master branch (68ad520)

classes/class_array.rst

@@ -501,6 +501,12 @@ Returns the last element of the array. Prints an error and returns ``null`` if t
 
 Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array.
 
+::
+
+    var array = ["a", "b", "c", "c", "d", "e"]
+    print(array.bsearch("c", true))  # Prints 2, at the first matching element.
+    print(array.bsearch("c", false)) # Prints 4, after the last matching element, pointing to "d".
+
 \ **Note:** Calling :ref:`bsearch<class_Array_method_bsearch>` on an unsorted array results in unexpected behavior.
 
 .. rst-class:: classref-item-separator
@@ -515,6 +521,8 @@ Finds the index of an existing value (or the insertion index that maintains sort
 
 Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return ``true`` if the first argument is less than the second, and return ``false`` otherwise.
 
+\ **Note:** The custom method must accept the two arguments in any order, you cannot rely on that the first argument will always be from the array.
+
 \ **Note:** Calling :ref:`bsearch_custom<class_Array_method_bsearch_custom>` on an unsorted array results in unexpected behavior.
 
 .. rst-class:: classref-item-separator