From 6be365240d64267e9ee8bad9e8ad6f6c71a469aa Mon Sep 17 00:00:00 2001
From: Sebastian Stock <42280794+sostock@users.noreply.github.com>
Date: Wed, 2 Jun 2021 19:08:59 +0200
Subject: [PATCH] Explain properties of the `lt` keyword for sorting (#41029)

* Explain restrictions on lt functions

* Remove warn block, add note in text
---
 base/sort.jl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/base/sort.jl b/base/sort.jl
index 6cdb0048274fc..afde46232cec1 100644
--- a/base/sort.jl
+++ b/base/sort.jl
@@ -669,7 +669,8 @@ 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.