From dae516dbdffaf771e072679a76a6d48f3f0aa182 Mon Sep 17 00:00:00 2001
From: yujiri8 <yujiri@disroot.org>
Date: Tue, 27 Jun 2023 03:51:06 -0400
Subject: [PATCH] improve documentation of std.sort.*Context functions (#16145)

---
 lib/std/sort.zig     | 8 ++++++--
 lib/std/sort/pdq.zig | 5 +++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/lib/std/sort.zig b/lib/std/sort.zig
index 48a54548e6..abeae29247 100644
--- a/lib/std/sort.zig
+++ b/lib/std/sort.zig
@@ -34,7 +34,9 @@ pub fn insertion(
 
 /// Stable in-place sort. O(n) best case, O(pow(n, 2)) worst case.
 /// O(1) memory (no allocator required).
-/// Sorts in ascending order with respect to the given `lessThan` function.
+/// `context` must have methods `swap` and `lessThan`,
+/// which each take 2 `usize` parameters indicating the index of an item.
+/// Sorts in ascending order with respect to `lessThan`.
 pub fn insertionContext(a: usize, b: usize, context: anytype) void {
     assert(a <= b);
 
@@ -73,7 +75,9 @@ pub fn heap(
 
 /// Unstable in-place sort. O(n*log(n)) best case, worst case and average case.
 /// O(1) memory (no allocator required).
-/// Sorts in ascending order with respect to the given `lessThan` function.
+/// `context` must have methods `swap` and `lessThan`,
+/// which each take 2 `usize` parameters indicating the index of an item.
+/// Sorts in ascending order with respect to `lessThan`.
 pub fn heapContext(a: usize, b: usize, context: anytype) void {
     assert(a <= b);
     // build the heap in linear time.
diff --git a/lib/std/sort/pdq.zig b/lib/std/sort/pdq.zig
index 795dd29fc5..0e1595b82c 100644
--- a/lib/std/sort/pdq.zig
+++ b/lib/std/sort/pdq.zig
@@ -37,8 +37,9 @@ const Hint = enum {
 
 /// Unstable in-place sort. O(n) best case, O(n*log(n)) worst case and average case.
 /// O(log(n)) memory (no allocator required).
-///
-/// Sorts in ascending order with respect to the given `lessThan` function.
+/// `context` must have methods `swap` and `lessThan`,
+/// which each take 2 `usize` parameters indicating the index of an item.
+/// Sorts in ascending order with respect to `lessThan`.
 pub fn pdqContext(a: usize, b: usize, context: anytype) void {
     // slices of up to this length get sorted using insertion sort.
     const max_insertion = 24;