Clojure.core/counted?的docstring应当更具体

Question

{{counted?}}的docstring目前说明：

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，这是我更好的docstring的第一个草稿。

Answer 2

评论者：gfredericks

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

Answer 3

评论者：alexmiller

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

我相信count处理的情况比仅适用于常数时间内计数的集合（如seqs）更多，所以并不打算与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部分，指出count?会为非Clojure集合返回false。在那里（以及不在那里的）单词被精心选择。

我同意你的看法，为了完全描述对这个或任何其他核心函数的预期，可能需要更多的文字。我从看待Rich对这类事物的响应中得到的经验是，他也可能同意这一点，但他更希望这些内容生活在文档字符串之外，如参考资料或其他来源中。并不是说我们不更新文档字符串，因为这种更新确实很常见；我只是觉得这个不会被执行。我还让Stu让我审阅第二遍。

Answer 9

评论者：gfredericks

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

Answer 10

评论人：arrdem

我觉得这个没问题，因为count的文档字符串明确指出“同样适用于...”，也就是说这些不需要count?。

Answer 11

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