clojure - 自定义定义的文档字符串

Question

在我正在进行的项目中，我们经常定义自定义 defsomething用于不同目的的样式宏来隐藏样板。一个例子是 defhook这有助于为事件定义 Hook 处理程序。这是它的简化版本(实际版本有更多参数，并且在 defmethod 中做了一些重要的事情，但这与我的问题无关):

(defmulti handle-hook
  "This multimethod is called when an event was fired."
  (fn [event context] event))

(defmacro defhook
  "Define a hook for an event."
  [event docstring & more]
  `(let [body# (fn ~@more)]
     (defmethod handle-hook ~event [event# context#]
       (body# context#))))

(defhook "EntryDeleted"
  "Hook called on entry deletion."
  [context]
  (log-deletion (:EntryID context)))

我对这段代码的主要问题是 defmethod不支持文档字符串，所以我不能使用 "EntryDeleted" 的那个在 REPL 中或用于自动文档生成。最后一个对项目很重要:有 defhook s 和 defhandler作为外部 API 公开的 s，目前我们必须单独(和手动)维护文档。

所以最简单的问题是“如何将文档字符串附加到 defmethod ”？

更深层次的问题是“如何为自定义 defsomething 宏附加/生成文档？”

如果一些现有的文档生成工具支持此功能，那就太好了!然而， Marginalia , Codox或 Autodoc似乎支持这样的事情。

Answer 1

How to attach/generate documentation for custom defsomething macros?

由于文档字符串附加到变量，您通常会拥有 defsomething宏扩展为更原始的 def形式，例如 defn , def .然后您只需安排您的 defsomething的文档字符串附加到基础 var。

How to attach docstring to a defmethod?

这是一个特例 - defmethod没有定义一个新的变量；它在 Java 对象上调用 Java 方法。另一方面， defmulti确实创建了一个var。一种想法是使用调度值和相关描述来扩展多功能的文档字符串。例如，

(defn append-hook-doc! [event docstring]
  (let [hook-doc (str event " - " docstring)]
    (alter-meta! #'handle-hook
                 (fn [m]
                   (update-in m [:doc] #(str % "\n\t" hook-doc))))))
...
(doc handle-hook)
-------------------------
user/handle-hook
  This multimethod is called when an event was fired.
      EntryDeleted - Hook called on entry deletion.

作为 !表明，这种形式有一个副作用:对调用它的定义形式的多次评估将导致 #'handle-hook 中的重复行。的文档字符串。您可以通过在 #'handle-hook 中存储一些额外的元数据来避免这种情况。用作文档是否已附加的标记。或者，您可以将文档字符串存储在其他地方并在某个辅助步骤中将它们全部修补在一起，例如通过延迟 (defmulti handle-hook ... 的扩展直到你拥有所有的文档字符串(尽管，这打破了多方法 wrt 文档字符串的开放扩展)。