clojure - clojure 中的记录文档

Question

我以前有一个 api，其中有许多函数，所有这些函数都需要一个非常特殊格式的 map 。在记录这个 API 时，我发现在每个函数的文档字符串中，我都在重复“调用这个函数的 map 必须是这样那样的格式，而 map 的这个字段意味着这样那样.”

所以我认为这些功能最好记录下来，而我可以只记录记录。然而，似乎不可能记录记录，至少以任何方式由 doc 解释。宏或边际。

建议的解决方案 here是“只需在记录的元中添加一个 :doc 键”。

我试过 (defrecord ^{:doc "Here is some documentation"} MyRecord [field1 field2])但是宏观扩展这表明它没有任何影响。还有 defrecord返回 java.lang.class 的实例它没有实现 IMeta 所以我不确定我们可以给它元数据吗？

记录应该如何记录？

记录在这里是合适的解决方案吗？

Answer 1

TL;博士:不幸的是你不能。

来自 docs :

Symbols and collections support metadata

当您使用 defrecord您实际上是在创建一个 java 类。由于类既不是符号也不是 Clojure 记录，因此您不能向它们附加文档。

更详细的解释

以下 REPL session 显示了为什么不能将元数据附加到记录。

user=> (defrecord A [a b])
#<Class@61f53f0e user.A>
user=> (meta A)  ;; <= A contains no metadata
nil  

这里要注意的重要一点是 A 是一个普通的 java 类。
如果您尝试为 A 设置元数据，您将收到一个有趣的错误

user=> (with-meta A {:doc "Hello"}) 

ClassCastException java.lang.Class cannot be cast to clojure.lang.IObj

显然 with-meta 期望 clojure.lang.IObj .自 java.lang.Class是一个 Java-land 构造，它显然对 clojure.lang.IObj 一无所知.

现在让我们看看 with-meta 的源代码

user=> (source with-meta)
(def
 ^{:arglists '([^clojure.lang.IObj obj m])
   :doc "Returns an object of the same type and value as obj, with
    map m as its metadata."
   :added "1.0"
   :static true}
 with-meta (fn ^:static with-meta [^clojure.lang.IObj x m]
             (. x (withMeta m))))

如您所见，此方法需要 x有一个 withMeta对象，这些记录显然没有。