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

Question

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

bq. 如果col实现count操作在常数时间内返回true

这会诱使用户认为他们可以用这个函数来确定调用任何集合上的count操作是否是常数时间的，而事实上，它仅仅反映了对象是否实现了{{clojure.lang.Counted}}接口。由于{{count}}会对一些平台类型进行特殊处理，因此像数组(String)和字符串这样常见的操作是常数时间的，但将从{{counted?}}返回false。

*建议：*

bq. 如果col，一个Clojure集合实现了count操作在常数时间内，返回true。注意，即使count函数可以以常数时间返回其大小，此函数对于宿主类型也将返回false（例如数组(String)）。

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

总的来说，docstrings更倾向于简洁和核心，而不是详尽的案例或举例。我的猜想是，docstring说的是Rich想要说的，并且他可能认为你添加的观点在当前docstring中已经隐含，因此不需要。具体来说，“coll”在所有的docstrings中都用得比较一致，表示Clojure集合（或序列）。在docstring中有一个隐含的else语句，说明count?对于非Clojure集合将返回false。存在的以及不存在的单词都被精心选择。

我同意你的观点，可能需要更多的文字来完整地描述这个或任何其他核心函数的预期。根据我对Rich对此类回应的经验，他可能也同意这个观点，但他可能更希望它在参考材料或其他来源之外的地方存在。这并不是说我们不会更新docstring，因为这确实很常见的；我只是不认为这个会被接受。我还让Stu给我提供了另一个意见。

Answer 9

评论者：gfredericks

这是有用的细节，谢谢！

Answer 10

评论人：arrdem

我认为这个是可以的，因为count的docstring明确注明“也适用于...”，这意味着这些不是count?要计算的对象。

Answer 11

参考：[CLJ-1607](https://clojure.atlassian.net/browse/CLJ-1607)（由 gfredericks 提出）