= - 文档可能不够精确

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](https://clojure.org/guides/equality)

我不知道核心Clojure团队是否会愿意在官方文档字符串中添加对该文章的链接，但这确实是在人们对其内容感到好奇时引导他们到文章的一种方式。

Comments

什么一篇精彩的文章！！！有很多我不知道的东西。

现在，就我个人而言，我很希望能够找到关于=（轻松地）的这种高质量的文档...

此外，我现在想撤回我对如何更改文档的原始建议，因为显然可以做得比那更好！（无论是通过链接还是其他方式...）

---

我想知道你是否已经寻找过这样的文档，如果是的话，在哪里？谷歌搜索“Clojure等价”将这个指南作为第一个搜索结果，clojure.org的搜索也可以找到第一个结果。

---

...嘻嘻...好吧，真是一针见血，...说实话，我所做的一切都只是从我的代码到源代码跟下来，然后阅读了文档，然后我想，...嗯...就是我所提到的 exactly what i posted about....

...所以... 我明白了你的意思，也许我本可以进行更彻底的在线搜索，...不过，至少对我而言，现在的文档似乎并不完全是正确的。

---

@alexmiller .... 所以.... 你已经有时间思考这个问题了吗？...... 我仍然认为我指出这一点是正确的，所以...

---

请注意，文档字符串编译成了作为“Clojure”发布的 JAR 文件，因此增加文档字符串会给所有使用 Clojure 的人带来（小）直接成本，无论他们是否查看这些文档字符串。

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

有很多 clojure.core 的文档字符串可以合理地得到改进，无论是提供类似于你在这里突出指出的澄清，还是添加示例，或扩展描述，或更清晰地定义使用其中的术语，但这些都会给 Clojure 实体增添开销，所以这些工作都不应该轻易开始。对 Clojure 本身的更改——即使只是文档字符串的更改——也需要 Cognitect 的 Clojure 核心维护团队的工作，这样就会从他们为语言用户带来好处的其他事情中抽走他们的时间。

在 clojure.org 本身上扩展材料是没有这种成本（除了志愿者愿意贡献他们的时间来创建/扩展这些材料之外）——除了 Alex 等人的监管工作来审查和合并此类内容，这个门槛比 Clojure 本身低得多。

---

@Sean Corfield 首先感谢您的回答！(……对于我有时候想得到的更多（有用的）反馈……而且我想你可能是一直愿意从忙碌的日程中抽出时间的那个人……去写/给予一些回应……所以我真的很感激！！！……我的意思是……比如我们讨论 datomic 和数据库的那段时间……即使我们没有得出相同的结论……仍然感觉不错，知道世界上至少有人对这类东西有点关心……(...而且愿意就这一点进行一些讨论 - :-) ……)))

无论如何……所以……这次我认为你也提出了很好的、有根据的观点……但无论如何，我担心这种做法/权衡在不可避免地（……以及其他事情）的结果是增加对新手的学习门槛……比如我在这个关于等式的视频中做的那样( https://www.youtube.com/watch?v=MhzXMiYdUxQ )……你可以看到当人们只是在代码周围看看、探索一些东西时，会发生什么……以及一些人可能会因为这种简洁的文档而有些困惑/被误导（……请注意，这个视频很长……这里相关的部分在大约 30 分钟处）

---

文档字符串的具体内容取决于Rich Hickey和其他少数人。他们有明确的偏好，喜欢简洁的文档字符串。过去曾多次被评论过，看起来不太可能改变。ClojureDocs.org有一些由社区创建的示例和内容来补充这一部分，但这些不是“官方”的，可能包含一些误解。另一个我尚未阅读的非官方来源是《Clojure的快乐》和《Clojure：经典参考》两本书，它们包含了对Clojure用户研究的结果。