chunk-* 函数未文档化

Question

在 core.clj 中定义的与 chunk 相关的所有函数都没有文档说明。虽然它们的实现很简单，但这意味着这些函数没有显示在 https://clojure.org/api 上。这些函数不是被视为 API 的一部分吗？如果是这样，它们应该私有吗？否则，我认为它们应该有公开的文档。

为了便于搜索，以下函数名称是什么？

chunk-append, chunk, chunk-first, chunk-rest, chunk-next, chunk-cons, chunked-seq?

Answer 1

评论由：benmoss 添加

尽量以我所理解的方式解释这些函数。

Answer 2

评论由：jafingerhut 添加

Ben，为 defn 添加文档字符串的正确顺序如下

(defn ^:static ^clojure.lang.ChunkBuffer chunk-buffer "返回指定容量的固定长度缓冲区。" ^clojure.lang.ChunkBuffer [capacity] (clojure.lang.ChunkBuffer. capacity))

文档字符串应在命名该函数的符号之后，但在参数向量之前。

Clojure 编译器在指定顺序执行时不会出现错误或警告，这是真的。然而，它也不会将提供的字符串附加为文档元数据，因此 (doc fn-name) 将不会打印文档字符串。

您能否更新补丁，将建议的文档字符串放在正确的位置？

Answer 3

评论由：alexmiller 添加

仅供参考，clojure.core中存在一些非私有函数（因为它们对外部实现者有用）但也没有在文档中说明，所以它们不会出现在公共API中（因为它们不被视为API的一部分）。这些函数可能属于这一类别，并且是故意没有文档的，但我并不确定。

Answer 4

评论由：benmoss 添加

对不起，Andy，对于这些是否应该全部记录，我真的不知道。

Answer 5

评论由：jafingerhut 添加

Ben，这确实是一个新手和学习了Clojure的开发者都会犯的错误，因为我已经从许多Clojure项目的实践中学到了这一点。Clojure本身（以及我想可能现在仍然如此）存在一些类似的情况。

Answer 6

评论由：jafingerhut 添加

Ben，你于2014年8月6日提交的补丁文件document_chunk_fns_v2.patch可以干净地应用到最新的master分支上，但会导致Clojure的测试失败。这是因为有一个测试确保clojure.core中带有doc字符串的每个函数都有:added元数据。如果您为添加doc字符串的函数创建:added元数据，则可以纠正这个问题。在core.clj中搜索:added以获取示例。请参阅此维基页面上的“如何运行所有Clojure测试”：http://dev.clojure.org/display/community/Developing+Patches

Answer 7

参考资料：https://clojure.atlassian.net/browse/CLJ-1002（由jim.blomo报告）