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项目中学到了这一点。在Clojure本身中（我想现在仍然如此）有一些这样的实例。

Answer 6

评论人：jafingerhut

Ben，您于2014年8月6日创建的补丁文档 chunk_fns_v2.patch 可以干净地应用到最新的master版本上，但它会导致Clojure的测试失败。这是因为有一个测试确保clojure.core中每个有文档字符串的函数都有：added元数据。如果您为添加文档字符串的函数创建了：added元数据，则可以纠正这一点。请在 core.clj 中搜索：added 来查看示例。请参阅此维基页面上的“如何运行所有Clojure测试”：[链接](http://dev.clojure.org/display/community/Developing+Patches)

Answer 7

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