From aec956d7c6272ba06723814f608ace852851f537 Mon Sep 17 00:00:00 2001
From: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
Date: Fri, 8 Mar 2024 12:37:05 +0100
Subject: [PATCH] [Doc] Clarify `bsearch(_custom)` behavior

* Added an example for the effect of `before`
* Clarified the arguments to the custom callable can be either order

(cherry picked from commit 06df4abcd3386007812b8c5a19f82607fae7c1ef)
---
 doc/classes/Array.xml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 2f8e9f8e0b39..ed4f9e783cbc 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -218,6 +218,11 @@
 			<param index="1" name="before" type="bool" default="true" />
 			<description>
 				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 [param before] specifier can be passed. If [code]false[/code], the returned index comes after all existing entries of the value in the array.
+				[codeblock]
+				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".
+				[/codeblock]
 				[b]Note:[/b] Calling [method bsearch] on an unsorted array results in unexpected behavior.
 			</description>
 		</method>
@@ -228,6 +233,7 @@
 			<param index="2" name="before" type="bool" default="true" />
 			<description>
 				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 [param before] specifier can be passed. If [code]false[/code], 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 [code]true[/code] if the first argument is less than the second, and return [code]false[/code] otherwise.
+				[b]Note:[/b] 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.
 				[b]Note:[/b] Calling [method bsearch_custom] on an unsorted array results in unexpected behavior.
 			</description>
 		</method>