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的一部分）。这些函数可能属于这一类别，并且故意没有文档化，但我不确定。

Answer 4

评论者：benmoss

对不起，安迪，这是一个新手错误。至于这些是否应该文档化，我并不清楚。

Answer 5

评论者：jafingerhut

本，这是一个新手和中级Clojure开发者的错误，正如我从运行许多由经验丰富的Clojure开发者编写的Clojure项目上的Eastwood所学到的那样。Clojure本身中（我想现在仍是有）存在一些这种情况。

Answer 6

评论者：jafingerhut

本，您于2014年8月6日发布的补丁文档chunk_document_fns_v2.patch可以干净地应用于最新主版本，但会导致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报告）