sort 函数的文档问题

Question

{{sort}} 函数的文档似乎不完整

• {{sort}} 在某些情况下可能返回 {{nil}}。在 CTYP-228 中有关于更多背景的讨论。这里有一个由 Nicola Mometto 提供的重现案例：http://sprunge.us/VIFc?clj。文档字符串声明 sort "返回 coll 中项的排序序列"，但没有指出 sort 可以返回 {{nil}}。

• 声明说“比较器必须实现 java.util.Comparator”，但这是错误的 - 比较器可以是任何能够接受两个参数并返回 Boolean 或 Number 的 IFn。

对于第一个问题（nil 返回），将实现更改为永不返回 nil 可能是最佳的修复方法。对于第二个问题，doc 字符串可以引用关于有效比较函数的描述，这些函数可以被其他接受比较器的函数引用（例如，{{sort-by}}, {{sorted-set-by}}, {{sorted-map-by}})。

Answer 1

评论者：alexmiller

第一个问题已在 CLJ-1763 中得到解决，所以我会把它从票据中移除。

第二个在技术上是正确的 - Arrays.sort() 会调用并接受一个 Comparator。棘手的是，AFn 基类实现了 Comparator，因此所有扩展它的并支持二维函数的实现都满足这个约束。但也许更好的是更清楚地说明这一点。

Answer 2

评论者：marc

在这里进行一个简单的修复，我可以只是声明sort方法需要一个比较函数，并让用户查阅参考手册获得比较函数的详细信息。我没有在参考手册中找到任何信息，但Clojure指南中有对比较函数的良好描述 - https://clojure.org/guides/comparators。我考虑为参考手册编写一个关于比较器的简短条目 - 这个主意怎么样？

Answer 3

评论者：alexmiller

这个问题应该重写以删除第一个问题。至于第二个问题，我认为添加一条条款/句子来说明比较器可以是一个返回布尔值或数字的2-参数函数是合适的。

如果您想更新网站，您应该在https://github.com/clojure/clojure-site上作为一个问题或PR来执行。

Answer 4

参考： https://clojure.atlassian.net/browse/CLJ-1767（由 marc 提交）