= - 文档可能不够精确

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语言用户的事情中抽取他们的时间。

在clojure.org本身上扩展内容不会产生这样的成本（除了志愿者愿意贡献他们的时间来创建/扩展这些材料之外）——除了Alex等人进行审查和合并此类内容的审核工作，这个门槛远低于Clojure本身。

---

@Sean Corfield 首先非常感谢您的回答！（关于我所有的问题/评论，有时我希望能得到更多（有用）的反馈……我猜您可能是那种总是愿意从忙碌的日程中抽出时间的人……并且为此写点什么/给予回应……所以我真的很感激！……我的意思是……比如我们讨论datomic和数据库的时候……即使我们没有达成相同的结论……但知道至少有人对这类事情有点关心也是让人感到很高兴的……（……以及愿意就此讨论一番（:-）……）……））

无论如何……这次我感觉，您提出了很好的而且有道理的观点……但恐怕这种做法/权衡不可避免地（……以及其他因素……）会导致初学者的入门门槛更高……例如，在我做的关于等性的这个视频中（https://www.youtube.com/watch?v=MhzXMiYdUxQ）……你可以看到当人们只是四处查看代码、探索时会发生什么……以及人们可能会因为这种简洁的文档而感到一些困惑/误导（……请注意，这个视频相当长……与我们这里相关的部分大约在第30分钟处）

---

关于文档字符串的内容，实际上由Rich Hickey和其他少数人决定。他们明显倾向于简洁的文档字符串。过去已经有人多次评论过这一点，并且看起来不太可能改变。ClojureDocs.org提供了社区创建的示例和内容来补充这一点，但它们不是“官方”的，可能包含一些误解。另一个我还没有阅读的非官方来源，但它们包含了对Clojure用户极端兴趣的研究结果，是书籍《Clojure的快乐》和《Clojure：必备参考》。