我以前有一个 api,其中有许多函数,所有这些函数都需要一个非常特殊格式的 map 。在记录这个 API 时,我发现在每个函数的文档字符串中,我都在重复“调用这个函数的 map 必须是这样那样的格式,而 map 的这个字段意味着这样那样.”
所以我认为这些功能最好记录下来,而我可以只记录记录。然而,似乎不可能记录记录,至少以任何方式由 doc
解释。宏或边际。
建议的解决方案 here是“只需在记录的元中添加一个 :doc 键”。
我试过 (defrecord ^{:doc "Here is some documentation"} MyRecord [field1 field2])
但是宏观扩展这表明它没有任何影响。还有 defrecord
返回 java.lang.class
的实例它没有实现 IMeta 所以我不确定我们可以给它元数据吗?
最佳答案
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
对象,这些记录显然没有。
关于clojure - clojure 中的记录文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/26454239/