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项目中运行Eastwood所了解到的那样。Clojure自身中也有（我想现在仍然有）一些这样的例子。

Answer 6

评论者为：jafingerhut

Ben，你于2014年8月6日提交的补丁文档chunk_fns_v2.patch可以干净地应用于最新的master版本，但会导致Clojure测试失败。这是因为有一个测试确保clojure.core中每个带有文档字符串的函数也有:added元数据。如果你为添加文档字符串的函数创建:added元数据，这个问题就可以解决。在core.clj中搜索:added以获取示例。有关如何在Clojure项目中运行所有测试的说明，请参阅此维基页面："如何在Clojure项目中开发补丁"：http://dev.clojure.org/display/common chDeveloping+Patches

Answer 7

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