如何调用函数以生成文档字符串？

Question

我对能否定义如下函数感到好奇

(defn my-cli-func
  (docstr 
    :description "Some CLI function with complex args to do something cool"
    [["-p" "--port" :port "Port to listen for connections on"]])
  [args]
  "...")

我的意图是希望 docstr 能够以一种一致的格式生成文档字符串，以便我进行验证。但是，由于参数声明错误，这种方法没有奏效。

我猜测可能可以使用 defn 包装宏来实现，但现在可能不值得麻烦。

我想知道是否有一些设计决策不允许元编程，或者是因为实现而出现某种机械限制。

Answer 1

 ~ % clj
Clojure 1.10.1
user=> (defn ^{:doc (str "foo" "bar")} f [x] x)
#'user/f
user=> (doc f)
-------------------------
user/f
([x])
  foobar
nil
user=>

替换 str 调用为所需的任何内容。您也可以事后更改文档字符串。

user=> (alter-meta! #'f assoc :doc "something")
{:doc "something", :arglists ([x]), :line 1, :column 1, :file "NO_SOURCE_PATH", :name f, :ns #object[clojure.lang.Namespace 0x72ba28ee "user"]}
user=> (doc f)
-------------------------
user/f
([x])
  something
nil
user=>

Comments

关于查询中的“验证”部分：alter-meta!的方式是可行的（它更像是基础情况而不是例外情况），因为在Clojure中你可以自由地以任何适合你的方式设置变量。实际上，Clojure提供了多种方式作为示例，包括defn、defrecord、defmulti等，而且绝对不是一个封闭的集合。因此，严格来说，找到并检查文档字符串的唯一方式是评估形式，然后查询Clojure环境以获取变量的元数据。

---

哦，我完全忘了这个API。这真的很惊人。谢谢！

---

有点离题，但我在几年前做了这个玩意儿（当然我从未使用过）https://github.com/slipset/checkdoc