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项目运行Eastwood时所学到的那样。Clojure本身（我想仍然是）存在一些这种情况的实例。

Answer 6

评论者：jafingerhut

Ben，您于2014年8月6日创建的补丁文档 chunk_document_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报告）