更新 sort-by 和 sort 的文档字符串，以指示它们将是稳定的排序

Question

Clojure 的 sort 和 sort-by 都承诺 "保证稳定性：相等的元素不会被重新排序。"

ClojureScript 中 sort 和 sort-by 的当前实现来自

9ee4dbf63d3968b70f29708aa03aace98cdcb624 作者：Stuart Halloway <[email protected]> 作者日期：Thu Jul 14 12:18:34 2011 -0500

`
(defn sort
"返回 coll 中项的排序序列。Comp 可以是
布尔值比较函数，或值比较器。
Comp 的默认值是 compare."
([coll]
(sort compare coll))
([comp coll]
(if (seq coll)

 (let [a (to-array coll)]
   ;; matching Clojure's stable sort, though docs don't promise it
   (garray/stableSort a (fn->comparator comp))
   (seq a))
 ())))

(defn sort-by
"返回 coll 中项的排序序列，其中排序
顺序由比较 (keyfn item)。Comp 可以是
布尔值比较函数，或值比较器。
Comp 的默认值是 compare."
([keyfn coll]
(sort-by keyfn compare coll))
([keyfn comp coll]

 (sort (fn [x y] ((fn->comparator comp) (keyfn x) (keyfn y))) coll)))

`

由于这个实现显然已经调用 google 的 stableSort 前八年，或许文档字符串可以修改以反映这一事实。

参考：google closure array 文档：(链接：https://google.github.io/closure-library/api/goog.array.html)

请注意，stableSort 的文档字符串实际上并没有提到稳定性，但排序函数包含 "此排序不保证稳定性。"

Answer 1

评论者：seancorfield

(从 Slack 上的讨论中来，我提供了这个意见，有人建议我将它添加到这个工单中)

我认为明确说明以下内容会更好：

Guaranteed to be stable: equal elements will not be reordered.

或者

Not guaranteed to be stable.

这样开发者就会 知道 他们可以依靠稳定性，或者他们不应该 依赖它（即使当前实现碰巧是稳定的）。

Answer 2

评论者：pbwolf

Clojure排序的文档字符串说明，"保证稳定性：相等的元素不会被重新排序。"之前它曾经是稳定的，但没有说明。参见https://dev.clojure.org/jira/browse/CLJ-1414

我希望CLJS (a) 以相同的方式保持稳定，并且 (b) 与Clojure的稳定性文档相符。

Answer 3

评论者：saurabh

如果这个问题 still open，我希望能够工作在这个问题上

Answer 4

评论者：dnolen

去做吧，你已经提交了你的CA了吗？

Answer 5

参考： https://clojure.atlassian.net/browse/CLJS-3035 (由dpsutton报告)