clojure.core/counted? 的文档注释应该更具体

Question

目前，{{counted?}} 的文档说明为

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

这使得用户误以为可以使用此函数来确定在对任何集合调用 {{count}} 时是否为常数时间操作，而实际上它仅反映了对象是否实现了 {{clojure.lang.Counted}} 接口。由于 {{count}} 特殊处理了平台类型的一小组，因此有一些常见情况，例如数组字符串，它们可以常数时间返回大小，但 {{counted?}} 将返回 false。

*建议：*

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

Answer 1

评论者：gfredericks

附上 CLJ-1607-p1.patch，其中包含我更好的文档字符串的第一个草案。

Answer 2

评论者：gfredericks

描述异常最准确的语言是什么？我在第一个补丁中使用了 "some collections"，但也许 "native collections" 或 "host collections" 会更有帮助？

Answer 3

评论者：alexmiller

虽然我理解你的观点，但“可计数？”的意图并非对所有可能的类型回答“这个事物是否可以在常数时间内计数”这个问题，而是专门针对那些参与Clojure集合库的集合。这包括PHM、PHS、PV等内部集合，还包括使用这些接口标记其能力的外部集合。

我相信count处理的情况不仅仅是常数时间内计数的集合（如序列），因此它不被设计成与counted?对称。

Answer 4

评论者：gfredericks

当然，我并没有建议改变函数的功能——只是想要修改docstring，使其更不易产生误导。

Answer 5

评论者：gfredericks

这种措辞怎么样？

如果Clojure集合coll实现了常数时间的count，则返回true。注意，即使_count_函数可以在常数时间内返回其大小，该函数也会为宿主类型返回false（如数组字符串）。

Answer 6

评论者：alexmiller

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

Answer 7

评论者：gfredericks

我试图弄清楚这里的分歧在哪里；你是在争论这些观点，还是其他观点？

1. docstring不太可能通过使人们认为它提供了对宿主集合有意义的响应来混淆他们。
2. 如果docstring混淆了人们，这不是我们应该解决的问题。
3. 这是我们应当解决的问题，但我提出的更改是一个不好的解决方案。

Answer 8

评论者：alexmiller

一般来说，文档字符串更倾向于简洁和本质，而不是详尽的例子或案例。我的怀疑是，文档字符串说的是Rich想要的内容，他认为你添加的点在当前文档字符串中是隐含的，因此没有必要。特别是，“coll”在所有文档字符串中一致地用来表示Clojure集合（或序列）。而在文档字符串中有一个隐含的else，表明count?会对非Clojure集合返回false。哪个词存在（或不存在）都是经过深思熟虑的选择。

我同意你的观点，可能会有更多的词来描述从这个函数到核心中任何其他函数的完整期望。从我看到Rich对此类事情的回应的经验来看，他可能也同意这一点，但他可能会更喜欢将其放在文档字符串之外的参考资料或其他来源中。我不是说我们不更新文档字符串，因为这种情况确实很常见；我只是不认为这个会通过。我还让Stu看了一眼。

Answer 9

评论者：gfredericks

谢谢这个有用的细节！

Answer 10

评论者：arrdem

我认为这个保持原样是可以的，因为count的文档字符串明确注明“Also works on ...”，这暗示了not-count?不会对这些进行计数。

Answer 11

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