clojure.core/counted?的文档串应该更加具体

Question

对于{{counted?}}的文档串目前说

bq. 如果coll实现了count在常数时间内，则返回true

这诱使用户认为他们可以使用此函数来决定对任何集合调用{{count}}是否是常数时间操作，但实际上它只反映对象是否实现了{{clojure.lang.Counted}}接口。因为{{count}}为一些平台类型进行了特殊处理，所以有一些常见的情况，如数组和字符串，它们是常数时间但将从{{counted?}}返回false。

**建议：**

bq. 如果clojure集合coll在常数时间内实现了count，则返回true。请注意，即使count函数能够在常数时间内返回其大小，此函数也将对宿主类型返回false（如数组字符串）。

Answer 1

评论由：gfredericks

附上CLJ-1607-p1.patch，这是我的更好的文档串的第一稿。

Answer 2

评论由：gfredericks

描述异常最准确的语言是什么？我在第一个补丁中使用了“一些集合”，但“本地集合”或“宿主集合”可能更有帮助？

Answer 3

评论者：alexmiller

虽然我理解你的观点，但我认为"能计数吗?"的意图并不是要回答“这个事物是否能在常数时间内计数”的所有可能类型，而是专门针对参与Clojure集合库的集合。这包括内部集合，如PHM、PHS、PV等，但也包括使用这些接口标记它们功能的外部集合。

我相信，count所能处理的情况比仅仅是计数时间恒定的集合（如序列）更多，所以不应该与counted?对称。

Answer 4

评论由：gfredericks

当然，我并没有建议更改函数的功能，只是更改一下文档字符串，使其不太可能产生误导。

Answer 5

评论由：gfredericks

这样的措辞如何？

当Clojure集合coll实现了常数时间的count方法时，返回true。请注意，即使大小函数可以在常数时间内返回其大小（如数组和字符串），但对于宿主类型，此函数仍将返回false。

Answer 6

评论者：alexmiller

我认为它不太可能通过审查，但这只是我的猜测。

Answer 7

评论由：gfredericks

我正在试图弄清楚这里的分歧在哪里；你是在争论这些观点中的任何一个，还是其他的不同观点？

1. 文档字符串不太可能导致人们对宿主集合产生误解，认为它提供了有意义的响应。
2. 如果文档字符串让人感到困惑，这不是我们解决的问题。
3. 这是我们应解决的问题，但我所提出的更改是错误的解决方案。

Answer 8

评论者：alexmiller

一般来说，文档字符串更喜欢简洁和本质，而不是详尽的示例或示例。我的怀疑是，文档字符串说了Rich想说的内容，他会认为你添加的观点在现有的文档字符串中是隐含的，因此不必要。具体来说，“coll”在所有文档字符串中都很一致地用来表示Clojure集合（或序列）。文档字符串中存在隐含的else，即counted?对于非Clojure集合将返回false。其中使用和未使用过的词汇都被仔细地选择了。

我同意你的观点，可能还需要更多词汇来完整描述从此类或其他任何核心函数中可以期望的内容。我从Rich对这些事物的回应中看到，他也可能同意这一点，但他更喜欢它存在于文档字符串之外的一些参考资料或其他来源中。不是说我们不更新文档字符串，因为那确实经常发生；我只是不认为这个会被接受。我让Stu也给我看了第二遍。

Answer 9

评论由：gfredericks

这个细节很有帮助，谢谢！

Answer 10

评论者：arrdem

我认为这个已经是好的，因为count的文档字符串明确指出“也适用于 ...”，这些隐含不适用于not-counted?。

Answer 11

参考： https://clojure.atlassian.net/browse/CLJ-1607 （由gfredericks报告）