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，添加doc字符串到defn的正确顺序如下：

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

doc字符串在函数名字符之后，但是在参数向量之前。

Clojure编译器按此顺序执行不会报错或警告，但这并不意味着它会将提供的字符串附加为文档元数据，因此(doc fn-name)不会打印出doc字符串。

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

Answer 3

评论者：alexmiller

请注意，clojure.core中有几个函数不是私有的（因为它们对内核以外的实现者也有用），但也没有被文档化，所以它们不会在公共API中显示（因为它们不被视为API的一部分）。这些函数可能属于这一类别，并且是故意没有被记录的，然而我不确定。

Answer 4

评论者：benmoss

对不起，Andy，这是一个菜鸟错误的。至于它们是不是打算被记录，我并不清楚。

Answer 5

评论者：jafingerhut

Ben，这是一个新手和经验丰富的Clojure开发者都可能犯的错误，因为我从运行许多经验丰富的Clojure开发者编写的Clojure项目中学到了这一点。Clojure本身也存在（我认为现在仍然存在）一些这种情况。

Answer 6

评论者：jafingerhut

Ben，你的补丁文档chunk_fns_v2.patch，日期为2014年8月6日，可以无冲突地应用到最新的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报告）