sort! docstring does not document order argument

[nalimilan]

Title says it all. That is particularly confusing is that "order" is mentioned twice, but in reference to rev, not to order.

help?> sort!
search: sort! sortperm! sort sortrows sortperm sortcols Cshort issorted

  sort!(v; alg::Algorithm=defalg(v), lt=isless, by=identity, rev::Bool=false, order::Ordering=Forward)

  Sort the vector v in place. QuickSort is used by default for numeric arrays
  while MergeSort is used for other arrays. You can specify an algorithm to
  use via the alg keyword (see Sorting Algorithms 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 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.

[dpsanders]

It seems to me that there are too many redundant options. Why is it not sufficient with just a single by argument, for example?

[nalimilan]

I guess there are cases in which you cannot reverse the sorting order without the rev argument: for reals, you can always use by=x -> -x, but it doesn't work e.g. for dates.

[andreasnoack]

But lt, rev, and order seem very overlapping.

julia> x = randn(4);

julia> sort(x, lt = (x,y) -> isless(y,x)) == sort(x, rev = true) == sort(x, order=Base.Order.Reverse)

true

julia> x = [(rand(1:2), rand(1:2)) for i in 1:5]
5-element Array{Tuple{Int64,Int64},1}:
 (1, 1)
 (1, 1)
 (2, 1)
 (2, 1)
 (2, 2)

julia> sort(x, lt = (x,y) -> isless(y,x)) == sort(x, rev = true) == sort(x, order=Base.Order.Reverse)

true

[dpsanders]

@nalimilan Ah, yes, maybe I meant a single lt argument.

[nalimilan]

I agree rev and order seem to overlap, though I don't know what the latter does since it's undocumented. OTOH passing lt = (x,y) -> isless(y,x) is quite verbose compared to rev=true.

[andreasnoack]

OTOH passing lt = (x,y) -> isless(y,x) is quite verbose compared to rev=true.

In most cases, you can just do lt = > which is shorter than rev=true. The verbosity is because of Julia's total/patial order thing and because we don't define isgreater.

[StefanKarpinski]

The order argument is kind of an implementation detail, so not documenting it was intentional. It will likely be removed in the next release. I suppose we could document it as a transient API in 0.6.

[nalimilan]

The problem is that it appears in the docstring. FWIW, this wasn't the case in 0.6. Should we just remove it?

[StefanKarpinski]

Your call.

[nalimilan]

I've filed #22388, applying the most radical fix.

[StefanKarpinski]

x-ref: #19295