多行Clojure文档字符串

时间:2012-05-23 03:11:35

标签: clojure documentation docstring

我注意到Clojure多行文档字符串似乎在大多数情况下都是手动格式化的,包括clojure.core中的那些。 https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj的示例:

(defn flatten
  "Takes any nested combination of sequential things (lists, vectors,
  etc.) and returns their contents as a single, flat sequence.
  (flatten nil) returns an empty sequence."
  {:added "1.2"
   :static true}
  [x]
  (filter (complement sequential?)
          (rest (tree-seq sequential? seq x))))

这看起来很奇怪,因为这意味着不同的文档字符串会有不同的换行长度等,需要手动维护。

有没有更好的方法来格式化多行文档字符串?

3 个答案:

答案 0 :(得分:13)

如果你正在使用Emacs,请从technomancy's Github抓取clojure-mode.el,这与ELPA中的clojure-fill-docstring不同(我不知道原因,两者都声称是版本1.11.5,也许有人可以对此进行评论?)但包含C-c M-q,它将格式化带有精简缩进和换行的文档字符串,默认绑定到(defn flatten "Takes any nested combination of sequential things (lists, vectors, etc.) and returns their contents as a single, flat sequence. (flatten nil) returns an empty sequence." {:added "1.2" :static true} [x] (filter (complement sequential?) (rest (tree-seq sequential? seq x))))

这需要:

(defn flatten
  "Takes any nested combination of sequential things (lists, vectors,
  etc.) and returns their contents as a single, flat sequence.
  (flatten nil) returns an empty sequence."
  {:added "1.2"
   :static true}
  [x]
  (filter (complement sequential?)
          (rest (tree-seq sequential? seq x))))

并将其转换为:

C-c M-q

在文档字符串中使用您的观点后{{1}}。

答案 1 :(得分:12)

  

有没有更好的方法来格式化多行文档字符串?

我的建议是在文档字符串中使用Markdown格式。以下是一些原因:

  • 这是在README和项目wiki中使用github的内容(许多Clojure用户使用并熟悉github)。

  • 根据各种Clojure项目中的number of .md files you find判断,它似乎是Clojure中首选的标记格式用户。

  • 热门的Marginalia doc工具呈现了markdown格式的文档字符串和注释(我的理解是Autodoc(用于在clojure.org生成文档的工具)最终将呈现markdown在docstrings中也是如此。

  • 它看起来很好,因为纯文本,易于输入,不需要任何特殊的编辑器支持,并且标记很小且易于记忆。

此外,您可能已经熟悉它,因为问题/答案/评论Stackoverflow uses it(以及reddit和各种博客评论系统等网站也使用Markdown)。

答案 2 :(得分:2)

我同意@uvtc认为降价是一个不错的选择。作为附录,我想要注意的是,生成自己的降价文档查看功能以便在REPL中使用是微不足道的。以下代码假定您在类路径上有markdown-clj包(例如,通过dev依赖项),并且在OSX中使用REPL:

(ns docs
  (:require [clojure.java.shell :as s]
            [markdown.core :as md]))

(defmacro opendoc [name]
   `(do
        (md/md-to-html (java.io.StringReader. (:doc (meta (var ~name)))) "/tmp/doc.html")
        (s/sh "open" "/tmp/doc.html")
    )
  )

您可能希望查看clojure.repl / doc的源代码以处理特殊情况(例如,假设您将为var传递正确的符号)。让文件名反映“缓存”的命名空间/函数名称可能也不错,而不是仅为每个请求重用相同的文件名...但是为了便于说明,我保持简单。

OSX open命令只是要求操作系统通过检测其类型来打开文件。因此:

REPL=> (docs/opendoc my.ns/f)

将导致您的默认浏览器打开函数文档字符串的HTML化版本。

另一个警告:如果你缩进你的多线字符串(编辑通常会这样做),那么你的MD可能最终会出现怪异(例如子弹列表可能以你不打算的方式嵌套)。解决这个问题的一种方法是将其修剪掉。例如:

(defn boo
  "
  # Title
  My thing

  * Item one
  * Item two
  "
  [args] ...)

然后修改opendoc函数以首先应用左边修剪:

(defn ltrim [str] (clojure.string/replace str #"(?m)^ {0,3}" ""))

(defmacro opendoc [name]
  `(do
    (md/md-to-html (java.io.StringReader. (ltrim (:doc (meta (var ~name))))) "/tmp/doc.html")
    (s/sh "open" "/tmp/doc.html")
   )
  )