clojure中的记录文档

Question

我以前有一个api，其中包含了许多函数，所有这些函数都期望一个非常特殊的格式的地图。在文档化这个API时，我发现在每个函数的文档字符串中，我重复了“调用该函数的映射必须是这样和这样的格式，而映射的这个字段就是这样和那样的。”

所以我认为这些函数最好记录下来，我可以直接记录下来。然而，似乎不可能记录记录，至少在任何方面都不可能被doc宏或Marginalia解释。

建议的这里解决方案是“只需在记录的元中添加a :doc键”。

我尝试过(defrecord ^{:doc "Here is some documentation"} MyRecord [field1 field2])，但是宏扩展表明它没有任何效果。另外，defrecord返回java.lang.class的一个实例，它没有实现IMeta，所以我不确定我们能不能给它元数据？

• 应如何记录记录？
• 在这里，记录是一个合适的解决方案吗？

Answer 1

TL;DR:，不幸的是你不能。

来自文档

符号和集合支持元数据

当您使用defrecord时，您实际上是在创建一个java类。因为类既不是符号，也不是Clojure记录，所以不能向它们追加文档。

更详细的解释

下面的REPL会话说明了为什么不可能将元数据附加到记录中。

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

显然-meta期望有一个clojure.lang.IObj。由于java.lang.Class是一个Java结构，所以它显然对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对象，而这个记录显然没有。

Answer 2

你不能把一个文档字符串记录下来。但如果你真的想这样做，那么你就可以有效地。

如果您希望阅读代码的用户知道您的意图，那么您可以向代码中添加注释。

如果希望创建记录实例的用户能够通过工具访问docstring，则可以修改创建的构造函数元数据。例如：

(let [docstring "The string-representation *MUST* be ISO8601."
      arglists '([string-representation millis-since-epoch])
      arglists-map '([{:keys [:string-representation :millis-since-epoch]}])]
  (defrecord Timestamp [string-representation millis-since-epoch])
  (alter-meta! #'->Timestamp assoc :doc docstring)
  (alter-meta! #'->Timestamp assoc :arglists arglists)
  (alter-meta! #'map->Timestamp assoc :doc docstring)
  (alter-meta! #'map->Timestamp assoc :arglists arglists-map))

对于我在草书中使用REPL，当我请求“参数信息”时，我会看到argslist弹出，当我请求“快速文档”时，我看到了docstring。

另一种更好的方法可能是为您自己的构造函数提供标准的docstring。