关于clojure.core/counted?的docstring应更具体

Question

{{counted?}}的docstring目前表示

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

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

*建议：*

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

Answer 1

评论由：gfredericks发表

附加CLJ-1607-p1.patch，这是我的改进版docstring的第一稿。

Answer 2

评论由：gfredericks发表

描述异常的最准确的语言是什么？我在第一次修复中使用了“一些集合”，但“本地集合”或“宿主集合”可能更合适？

Answer 3

评论者：alexmiller

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

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

Answer 4

评论由：gfredericks发表

当然，我没有建议改变函数的行为，只是想修改文档字符串，使其不太可能产生误导。

Answer 5

评论由：gfredericks发表

这种表达方式怎么样？

如果 Clojure 集合 coll 实现了计数方法，则返回 true。请注意，即使可以常数时间内获取其大小（像数组字符串那样），这个函数对于宿主类型也会返回 false。

Answer 6

评论者：alexmiller

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

Answer 7

评论由：gfredericks发表

我正在试图弄清楚这里的分歧是什么；你是否在争论这些观点，或者其它不同之处？

1. 文档字符串不太可能导致人们对宿主集合有意义的响应产生误解。
2. 如果文档字符串让人们产生误解，这不是我们解决的问题。
3. 我们应该解决的是问题，但我觉得我所建议的更改是糟糕的解决方案。

Answer 8

评论者：alexmiller

一般来说，docstring 更倾向于简洁和精华，而不是详尽无遗的案例或示例。我怀疑 docstring 就是 Rich 想说的，并且他认为你增加的点在当前的 docstring 中已经隐含，因此没有必要。具体来说，“coll”在所有的 docstring 中都相当一致地用来表示 Clojure 集合（或序列）。在 docstring 中隐含了计数的else情况，即非 Clojure 集合的东西将会返回 false。存在于那里（或不存在于那里）的词都是精心挑选的。

我同意你的观点，可能需要更多的词汇来完全描述从 core 中的这个或其他任何函数可以期待什么。我从看到富瑞关于这类事物的回应中得出的经验是，他也可能同意这个观点，但他更倾向于把它放在参考材料或其它来源之外的某处。这并不意味着我们不会更新 docstring，因为这确实发生得相当频繁；我只是认为这个不会被接受。我已经要求 Stu 也给我一双眼睛审视。

Answer 9

评论由：gfredericks发表

这是一个有用的细节，谢谢！

Answer 10

评论者：arrdem

我认为这个（docstring）已经很好了，因为 count 的 docstring 明确提到了“也适用于 ...”，这暗示这不是 counted?要计数的。

Answer 11

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