slices: update BinarySearchFunc docs for CL 464456

In CL 464456 we updated BinarySearchFunc to permit different types
for the slice element and the target. Update the docs accordingly.

For golang/go#57348
Fixes golang/go#59685

Change-Id: I8bc3b81051628807fb2426a425101b8bad041ff9
Reviewed-on: https://go-review.googlesource.com/c/exp/+/485995
Reviewed-by: Eli Bendersky <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Run-TryBot: Ian Lance Taylor <[email protected]>
Run-TryBot: Ian Lance Taylor <[email protected]>
Auto-Submit: Ian Lance Taylor <[email protected]>

Author: ianlancetaylor

slices/sort.go

@@ -81,10 +81,12 @@ func BinarySearch[E constraints.Ordered](x []E, target E) (int, bool) {
 }
 
 // BinarySearchFunc works like BinarySearch, but uses a custom comparison
-// function. The slice must be sorted in increasing order, where "increasing" is
-// defined by cmp. cmp(a, b) is expected to return an integer comparing the two
-// parameters: 0 if a == b, a negative number if a < b and a positive number if
-// a > b.
+// function. The slice must be sorted in increasing order, where "increasing"
+// is defined by cmp. cmp should return 0 if the slice element matches
+// the target, a negative number if the slice element precedes the target,
+// or a positive number if the slice element follows the target.
+// cmp must implement the same ordering as the slice, such that if
+// cmp(a, t) < 0 and cmp(b, t) >= 0, then a must precede b in the slice.
 func BinarySearchFunc[E, T any](x []E, target T, cmp func(E, T) int) (int, bool) {
 	n := len(x)
 	// Define cmp(x[-1], target) < 0 and cmp(x[n], target) >= 0 .