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中，每个有doc字符串的函数都有:added元数据。如果为添加doc字符串的函数创建:added元数据，这就可以纠正。在core.clj中搜索:added查找示例。有关如何运行所有Clojure测试的信息，请参阅此维基页面：“如何在Clojure社区开发补丁”：http://dev.clojure.org/display/community/Developing Patches

Answer 7

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