slices: add documentation on incomparable items in SortFunc

Change-Id: Ib289008c0e9b5e83c37c9b6b316f3f5de8ac339a
Reviewed-on: https://go-review.googlesource.com/c/go/+/592617
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>

diff --git a/src/slices/sort.go b/src/slices/sort.go
index 4c20a2943c42da8b44cbba2b2d8a40067bb68f6d..f713ffe09473a727edcb959c4921add6831ebb4f 100644 (file)
--- a/src/slices/sort.go
+++ b/src/slices/sort.go
@@ -21,10 +21,12 @@ func Sort[S ~[]E, E cmp.Ordered](x S) {
 // SortFunc sorts the slice x in ascending order as determined by the cmp
 // function. This sort is not guaranteed to be stable.
 // cmp(a, b) should return a negative number when a < b, a positive number when
-// a > b and zero when a == b.
+// a > b and zero when a == b or a and b are incomparable in the sense of
+// a strict weak ordering.
 //
 // SortFunc requires that cmp is a strict weak ordering.
 // See https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings.
+// The function should return 0 for incomparable items.
 func SortFunc[S ~[]E, E any](x S, cmp func(a, b E) int) {
        n := len(x)
        pdqsortCmpFunc(x, 0, n, bits.Len(uint(n)), cmp)