chunk-* 函数未文档化

Question

核心.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

本，向 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开发者都会犯的错误，正如我从运行Eastwood在许多有经验的Clojure开发者编写的Clojure项目中学到的那样。Clojure本身中也有一些（我认为现在仍然有一些）这种情况。

Answer 6

评论者：jafingerhut

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

Answer 7

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