文档可能不够精确

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的搜索结果也将其列为第一个结果。

---

... 嗯...好吧，话说到点子上了,... 说实话，我所做的只是从我的代码跟到源，然后阅读文档... 然后我想，嗯... 正是我发表的关于那篇内容...

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

---

@alexmiller .... 所以.... 你对此有何看法？..... 我仍然认为我有权利指出这一点.....

---

请注意，Java字符串文档是根据“Clojure”随发行包编译的，因此增加文档字符串将直接给所有使用Clojure的人（无论他们是否查看文档字符串）带来（小的）成本。

从历史上看，文档字符串始终是对预期会被添加到clojure.org和各个社区管理的文档网站（或书籍）中的向导/参考材料的简短、精练的行为描述。

有大量的clojure.core文档字符串可以适当改进，无论是提供澄清，添加示例，扩展描述，还是更清晰地定义其中使用的术语，但所有这些都会给Clojure程序包增加额外的工作量，因此不应轻举妄动。对Clojure本身的更改——即使是文档字符串的更改——都需要Cogitect的Clojure核心维护团队的工作，这样就会从该语言的用户的其他受益活动中夺走他们的时间。

在clojure.org上扩展材料本身没有这样的成本（除了志愿者愿意贡献他们的时间来创建/扩展这种材料之外）——除了Alex等人对审查和合并这类内容的监管努力，这个门槛远低于Clojure本身。

---

@Sean Corfield 首先非常感谢您的回答！（...在我的所有问题/评论中，我有时也希望得到更多（有用）的反馈...我想你应该是那个在忙碌的日程中总是愿意抽时间给予回应的人...并且给予一些东西回馈...所以我真的很感激这一点！！！...我是说...例如，当我们谈论datomic和数据库时...即使我们没有得出相同的结论...但知道外面至少有人对此类问题有点关心，这仍然令人愉快...(...也有点想讨论这个问题 :-).... ))

无论如何...这一次，我认为你的观点很好，很有道理...然而，我担心这种方法/权衡不可避免地（...还有其他原因...）会提高初学者的入门门槛...例如，在这个关于等性的视频中，我？（ https://www.youtube.com/watch?v=MhzXMiYdUxQ ）...你可以看到当人们只是四处查看代码、探索事物时会发生什么...以及人们如何被这类简短的文档搞混/误导（...注意，这个视频相当长...这里相关的内容发生在30分钟附近...）

---

实际上，Rich Hickey和其他一些人决定文档字符串中包含什么内容。他们更喜欢简洁的文档字符串。过去被评论过N次，看起来不太可能改变。ClojureDocs.org有社区创建的示例和内容作为补充，但它们不是“官方”的，可能包含一些误解。另一个我没有阅读的非官方来源，但它们包含了对Clojure用户非常感兴趣的大量研究的结果，是书籍《Clojure的乐趣》和《Clojure：精华参考》。