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

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

我认为count处理的情况不仅限于在常数时间内计数的集合（如序列），因此并不打算和counted?对称。

Answer 4

评论人：gfredericks

当然，我并没有建议更改函数的功能，只是建议修改文档字符串以减少误导的可能性。

Answer 5

评论人：gfredericks

这种表述怎么样？

如果coll，一个Clojure集合，实现了在常数时间内进行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的文档字符串明确指出“也适用于...”，这些就是隐含不计入counted?的对象。

Answer 11

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