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

如何最准确地描述异常？我在第一个补丁中使用了“某些集合”，但可能“本地集合”或“宿主集合”更有帮助？

Answer 3

评论者：alexmiller

虽然我理解了您的立场，但我认为“counted?”的含义并非是针对所有可能类型的“这个事物是否可以在常数时间内计数”，而是特别针对参与Clojure集合库的集合。这既包括PHM、PHS、PV等内部集合，也指明通过这些接口来标记他们能力的源外集合。

count处理了比只是一种在常数时间内计数的集合（如序列）更多的情况，因此并不打算与counted?对称。

Answer 4

评论者：gfredericks

当然，我并没有建议改变函数的功能——只是修改文档字符串，使其更不可能产生误导。

Answer 5

评论者：gfredericks

这个词句怎么样？

如果coll是一个实现count的Clojure集合，则返回true。注意，即使count函数可以在常数时间内返回主机类型的大小，这个函数对主机类型也可能返回false（如数组和字符串）。

Answer 6

评论者：alexmiller

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

Answer 7

评论者：gfredericks

我在试图了解争议所在；你是在就这些观点进行争论，还是其他什么观点？

1. 这篇文档不会因为向人们展示它给出了有意义的响应而造成混淆。
2. 如果文档引起人们的混淆，并不是我们应该解决的问题。
3. 这是一个我们应该解决的问题，但我建议的改变是个坏主意。

Answer 8

评论者：alexmiller

通常，文档字符串更喜欢简洁和精华，而不是详尽的案例或示例。我的怀疑是文档字符串说了Rich想说的，他可能会认为你添加的点在当前文档字符串中是隐含的，因此没有必要。具体来说，“coll”在所有文档字符串中使用得相当一致，表示Clojure集合（或序列）。文档字符串中还有一个隐含的else，表示counted?将返回false对于不是Clojure集合的事物。那里（和不在那里）的词都是精心选择的。

我同意你需要更多的字眼才能完全描述这个或其他任何核心函数的预期结果。从看到Rich对这类事情的回应的经验来看，他也可能同意这一点，但他更愿意将这一点体现在外部文档字符串的参考材料或其他资源中。并不是说我们不会更新文档字符串，因为这确实很常见；我只是认为这个不会得到接受。我还让Stu给我看了第二眼。

Answer 9

评论者：gfredericks

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

Answer 10

评论者：arrdem

我认为这个没问题，因为count的文档字符串明确指出“也适用于...”，这些是未计数的隐含项。

Answer 11

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