文档可能不够精确

Question

看到=

(defn ^boolean =
  "Equality. Returns true if x equals y, false if not. Compares
  numbers and collections in a type-independent manner.  Clojure's immutable data
  structures define -equiv (and thus =) as a value, not an identity,
  comparison."
  ([x] true)
  ([x y]
    (if (nil? x)
      (nil? y)
      (or (identical? x y)
        ^boolean (-equiv x y))))
  ([x y & more]
     (if (= x y)
       (if (next more)
         (recur y (first more) (next more))
         (= y (first more)))
       false)))

以下内容让我感到惊讶

(= [1] #{1})

因为向量和集合都是集合，所以当它说

以类型无关的方式比较数字和集合。

我认为它应该说

以类型无关的方式比较数字、序列、映射和集合。
。

Answer 1

我无法确定文档字符串是否会改变，但我在Clojure =行为的边缘案例上投入了相当多的时间后，撰写了这篇关于相等性的指南文章：[《相等性的指南》](https://clojure.org/guides/equality)

我不知道Clojure的核心团队是否会愿意在官方文档字符串中添加指向该文章的链接，但如果人们对其内容感兴趣，这将是一种引导他们查看文章的方法。

Comments

多好的文章啊！！！很多东西我都不知道。

对我来说，能找到这样高质量的超文档（=容易）将是一件很棒的事情...

此外，我现在想撤回我之前关于如何更改文档的建议，因为很明显，人们可以做得比这更好！（无论是通过链接还是其他方式.... ）

---

我想知道你是否寻找过这样的文档，如果是的话，在哪里？谷歌搜索 "clojure equality" 时，这个指南是第一个结果，clojure.org 的搜索也将其作为第一个结果找到。

---

... 嗯... 好吧，观点很明确，... 说实话，我只是在代码和源代码间依次看了看... 然后我读了文档... 然后，我想，... 正是我发的那个帖子上的内容...

... 所以... ... 我明白了您的意思，或许我可以在网上做更彻底的搜索，... 但是，至少对我来说，文档目前并不完全正确。

---

@alexmiller ... 所以... 你已经有机会考虑这个问题了吗？... 我仍然认为我提出的问题很对... 所以...

---

请注意，文档字符串被编译进作为“Clojure”一起发布的 JAR 中，因此无论用户是否查看文档字符串，增加文档字符串都会给每个使用 Clojure 的人带来（小小的）直接成本。

历史上，文档字符串始终是对期望增强的行为的简短、简洁描述，这些行为将在 clojure.org 和各个社区管理文档网站上（或书籍中）的指南和参考资料材料中得到增强。

还有很多 clojure.core 的文档字符串可以合理地改进，例如添加此处强调的澄清、添加示例、扩展描述或更清晰地定义其所使用的术语。但所有这些都会给 Clojure 艺术品增加便利，所以不应轻率行事。对 Clojure 自身的更改——即使是文档字符串更改——也需要来自 Cognitect 的 Clojure 核心维护团队的工作，这样就会让这些人从其他有助于语言用户的事情上分心。

在 clojure.org 本身上扩展材料没有这样的成本（除了志愿者愿意贡献他们的时间来创建/扩展这些材料之外）——除了 Alex 等人进行审阅和合并此类内容的调解工作，而这项工作的门槛要低得多。

---

 @Sean Corfield 首先感谢您的回答！（…对于我所有的问题和评论，我有时希望能够得到更多（有用）的反馈……我想您一直是那些在忙碌的日程中愿意抽出时间的人……写下/给出一些东西……所以我真的很感激！……我是说……例如我们讨论 datomic 和数据库的那次……即使我们没有得出相同的结论……但知道有人在关心这种事也已经很不错了……（…并且愿意聊聊这种事:-)……）

任何情况下……所以……这次，我感觉，您提出了很好的和有效的观点……尽管如此，我担心这种方法/权衡不可避免地（…等等…）会导致新手的入门门槛提高……例如，在我关于等价性的这个视频中（https://www.youtube.com/watch?v=MhzXMiYdUxQ）……您可以看到，当人们只查看代码、探索事物时，会发生什么；当人可能会因为这种简洁的文档而感到有点困惑/误导。（…同时请注意，这个视频相当长……这里相关的内容发生在 30 分钟左右的地方…）

---

究竟谁会在文档字符串中加入内容，这取决于Rich Hickey和其他少数人。他们倾向于简洁的文档字符串。过去已经讨论过N次，几乎没有改变的可能。ClojureDocs.org提供了社区创建的示例和内容来补充这一部分，但它们不是“官方”的，可能包含一些误解。另一个我尚未阅读的非官方来源，但它们包含非常感兴趣的Clojure用户的大量研究成果，是《Clojure：乐趣》和《Clojure：必备参考》这两本书。