From bcb41adc6946bd3f87e1c6d23e193a5ddf0fc245 Mon Sep 17 00:00:00 2001
From: Sebastian Stock <42280794+sostock@users.noreply.github.com>
Date: Mon, 31 May 2021 19:49:55 +0200
Subject: [PATCH 1/2] Explain restrictions on lt functions

---
 base/sort.jl | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/base/sort.jl b/base/sort.jl
index 0946eec516ef7..d615932326714 100644
--- a/base/sort.jl
+++ b/base/sort.jl
@@ -674,6 +674,10 @@ options are independent and can be used together in all possible combinations: i
 and `lt` are specified, the `lt` function is applied to the result of the `by` function;
 `rev=true` reverses whatever ordering specified via the `by` and `lt` keywords.
 
+!!! warn
+    The `lt` function must be a "less than" function (as opposed to a "less than or equal" function),
+    i.e., for every `x` and `y`, only one of `lt(x,y)` and `lt(y,x)` can return `true`.
+
 # Examples
 ```jldoctest
 julia> v = [3, 1, 2]; sort!(v); v

From b7a213c62cb081b9b38e91a2dae773f180779a04 Mon Sep 17 00:00:00 2001
From: Sebastian Stock <42280794+sostock@users.noreply.github.com>
Date: Wed, 2 Jun 2021 11:34:50 +0200
Subject: [PATCH 2/2] Remove warn block, add note in text

---
 base/sort.jl | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/base/sort.jl b/base/sort.jl
index d615932326714..4f3c6eb18d9fe 100644
--- a/base/sort.jl
+++ b/base/sort.jl
@@ -669,15 +669,12 @@ Sort the vector `v` in place. [`QuickSort`](@ref) is used by default for numeric
 [`MergeSort`](@ref) is used for other arrays. You can specify an algorithm to use via the `alg`
 keyword (see [Sorting Algorithms](@ref) for available algorithms). The `by` keyword lets you provide
 a function that will be applied to each element before comparison; the `lt` keyword allows
-providing a custom "less than" function; use `rev=true` to reverse the sorting order. These
+providing a custom "less than" function (note that for every `x` and `y`, only one of `lt(x,y)`
+and `lt(y,x)` can return `true`); use `rev=true` to reverse the sorting order. These
 options are independent and can be used together in all possible combinations: if both `by`
 and `lt` are specified, the `lt` function is applied to the result of the `by` function;
 `rev=true` reverses whatever ordering specified via the `by` and `lt` keywords.
 
-!!! warn
-    The `lt` function must be a "less than" function (as opposed to a "less than or equal" function),
-    i.e., for every `x` and `y`, only one of `lt(x,y)` and `lt(y,x)` can return `true`.
-
 # Examples
 ```jldoctest
 julia> v = [3, 1, 2]; sort!(v); v