= - 文档可能不够精确

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 equality”进行谷歌搜索，这个指南是第一个结果，clojure.org搜索也将其作为第一个结果找到。

---

... 嗯嗯... 好吧，说的很好，... 说实话，我只是在代码中跟进去，然后阅读了文档... 然后 我想... ... 恰好是我所发表的...

... 那么 ...  我明白了你的意思，也许我应该更彻底地在网上搜索，.... 但是，至少对我来说，文档目前并不是100%正确。

---

@alexmiller .... 好吧，你对此有何感想？...... 我仍然认为指出这一点是正确的。

---

请注意，文档字符串会被编译进作为“Clojure”发布的JAR中，因此增加文档字符串会给使用Clojure的所有人带来（虽然不大）直接的成本，不管他们是否查看文档字符串。

在历史上，文档字符串一直是关于预期在clojure.org和各社区维护的文档站点（或在书中）中增强的行为的简短、简洁描述。

有大量 clojure.core 文档字符串可以合法地增强，例如提供您在这里强调的澄清、添加示例、扩展描述或更清楚地定义所使用的术语——但这所有内容都会为Clojure工件增加负担，因此不应轻率地执行。对Clojure本身的更改——即使是文档字符串的更改——也需要Cognitect的Clojure核心维护团队的工作，因此这会从他们为语言用户提供其他好处的事情中夺取他们的时间。

在clojure.org本身上扩展材料没有任何这种成本（其他成本只是志愿者愿意抽出时间创建/扩展这些材料的意愿）——除了Alex等人为了审查和合并此类内容的监管努力，这个门槛比Clojure本身低得多。

---

@Sean Corfield 首先非常感谢你的回答！（...内对于我的所有问题/评论，有时我希望能得到一点更多（有用的）反馈...而且我想你应该是那个在忙碌的日程中总是愿意抽出时间的人....来写/给出一些东西...所以我真的很感激！！！...意思是...比如当我们谈论Datomic和数据库的时候...即使我们没有得出相同的结论...但还是感觉很好，知道有人在关心这类事情... (...以及愿意对此进行一些讨论:-）...

anyway...这次我觉得你提出了好的、合理的观点...然而，我担心这种做法/权衡不可避免地（......等等......）会导致初学者的门槛更高...例如，在我做的这个关于等式的视频中（https://www.youtube.com/watch?v=MhzXMiYdUxQ）...你可以看到当人们只是四处看看代码、探索事物时会发生什么，以及有人可能会因为这种简略的文档而感到有些困惑/误导。（...另外，这个视频相当长...这里相关的内容大约在30分钟处...）

---

文档字符串的具体内容由Rich Hickey等人决定。他们更喜欢简洁的文档字符串。过去已经被评论了N次，看起来不太可能改变。ClojureDocs.org有社区创建的例子和内容来补充，但这些不是“官方”的，并且可能包含一些误解。另一个我没有阅读的“非官方”来源，但它们包含了大量由非常感兴趣的Clojure用户研究的结果，是《Clojure的乐趣》和《Clojure：必备参考》这两本书。