文档可能不够精确

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

太棒的文章了！！！有很多我不知道的东西。

对我来说，如果能找到关于=（easy）质量如此高的文档就太好了...

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

）

---

我很想了解你是否曾寻找过类似这样的文档，如果是，在哪里？在谷歌搜索“clojure equality”时，这篇指南成了第一个结果，clojure.org的搜索也将它作为第一个结果显示。

---

...嗯...好吧，观点正确，...说实话，我只是跟随着我的代码到源代码，然后阅读文档...然后我想，...嗯...正是我发布的内容。

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

---

@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：核心参考》。