可能文档不够精确

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和少数其他人。他们更喜欢简洁的文档字符串。过去已经被质疑过N次，似乎不太可能改变。ClojureDocs.org有社区创建的示例和内容来补充，但它们不是“官方”的，可能包含一些误解。另一位我还没有阅读的非官方来源，但其中包含了极度感兴趣的Clojure用户的大量研究结果是《Clojure的乐趣》和《Clojure：核心参考》。