可能文档不够精确

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搜索也将其作为第一个结果找到。

---

...嗯，相当中肯。说实话，我所做的就是跟随我的代码到源代码，然后读文档，然后我想，嗯...就是我想post的那个...

...所以...我知道你的意思了，也许我应该在网上做更彻底的搜索，...不管怎样，至少对我来说，文档看起来似乎并不是目前这种100%正确。

---

@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和其他几个人决定。他们明确偏好简洁的文档字符串。过去的历史上有N次的评论，看上去不太可能改变。ClojureDocs.org有社区创建的示例和内容来补充这些，但这些不是“官方的”，可能包含一些误解。另一个我没有读过的非官方来源，但它们包含非常感兴趣的Clojure用户进行的许多研究的结果，是《Clojure的快乐》和《Clojure：必读参考》这两本书。