= - 文档可能不够精确

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

---

... 嗯嗯... alright, point well taken,... truth be told, all i did was follow along from my code to the source... and then i read the doc... and then i thought,... well... exactly what i posted about....

... 所以 ....  i see what you mean, perhaps i could have done a more thorough search online, .... still, to me at least the doc does not seam like it is 100% correct the way it currently is.

---

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