Documentation Issues with sort

Question

The documentation for {{sort}} seems to be incomplete:

• {{sort}} can return {{nil}} in some situations. There is a discussion in CTYP-228 with more backstory. There is a repro case here: http://sprunge.us/VIFc?clj supplied by Nicola Mometto. The doc string states that sort "Returns a sorted sequence of the items in coll.", which does not indicate that sort can return {{nil}}.

• It is stated that the "comparator must implement java.util.Comparator.", but this is not true - the comparator can be any IFn that can accept 2 arguments and return either a Boolean or a Number.

For the first issue (nil return), changing the implementation to never return nil might be the neatest fix. For the second issue, the docstring could reference a description of how what functions are valid comparison functions, which can be referenced by other functions that also accept comparators (e.g., {{sort-by}}, {{sorted-set-by}}, {{sorted-map-by}}).

Answer 1

Comment made by: alexmiller

The first issue is being covered by CLJ-1763, so I would remove it from the ticket.

The second is technically true - Arrays.sort() will invoked and it takes a Comparator. The tricky bit is that AFn base class implements Comparator so all function implementations that extend from it that support a 2-arg function satisfy this constraint. But it might be helpful to call that out better.

Answer 2

Comment made by: marc

I was thinking that a neat fix here would be to just state that sort takes a comparator function, and let the user refer to the reference manual for details of comparator functions. I could not find anything in the reference manual, but the Clojure guide has a good description of comparators - https://clojure.org/guides/comparators. I'm thinking of writing a small entry for the reference manual to document comparators - how does that sound?

Answer 3

Comment made by: alexmiller

This issue should be rewritten to remove the first issue. For the second one, I think it would be ok to add a clause/sentence to cover that a comparator can be a 2-arg function that returns either a boolean or a number.

If you want to update the web site, you should do that as an issue or PR on https://github.com/clojure/clojure-site.

Answer 4

Reference: https://clojure.atlassian.net/browse/CLJ-1767 (reported by marc)