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

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