多行Clojure文档字符串

我注意到Clojure多行docstring在大多数情况下似乎是手动格式化的，包括Clojure.core中的那些。示例来自：

这似乎有些奇怪，因为这意味着不同的docstring将具有不同的换行长度等，需要手动维护

有没有更好的方法格式化多行docstring

有没有更好的方法格式化多行docstring

我的建议是在docstring中使用格式。以下是一些原因：

• 它是github在自述和项目Wiki中使用的（许多Clojure用户使用并熟悉github）

• 从各种Clojure项目的现状来看，它似乎是Clojure用户的首选标记格式

• 流行的doc工具呈现降价格式的docstring和注释（我的理解是（clojure.org上用于生成文档的工具）最终也会呈现docstring中的降价）

• 它看起来像纯文本，易于键入，不需要任何特殊的编辑器支持，并且标记非常小，易于记忆

---

另外，您可能已经熟悉它了，因为对于问题/答案/评论（以及reddit和各种博客评论系统等网站也使用降价）。

如果您使用的是Emacs，请抓取

clojure mode.el

from，这与ELPA中的不同（我不知道为什么，这两个版本都声称是1.11.5版，也许有人可以对此发表评论。）但包括

clojure fill docstring

，它将以良好的缩进和换行方式格式化docstring，默认情况下绑定到

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))))

---

在您将您的点放在docstring中之后，

C-C M-q

。

我同意@uvtc的观点，标记是一个不错的选择。作为补充，我想指出的是，生成您自己的标记文档查看函数以在REPL上使用是很简单的。下面的代码假设您的类路径上有标记clj包（例如，通过开发依赖项），并且正在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)

将导致默认浏览器打开函数docstring的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")
   )
  )

---

我认为解决这一问题的方法很大程度上取决于是否能够配置（或增强）编辑器，以便在您键入文档或根据需要格式化文档字符串。还有其他文档字符串约定也可以/应该形式化，例如，从let->

（let bindings&body）bindings=>binding form init expr

有趣的想法，我确实使用了标记，并且喜欢它用于其他事情（例如Github上的README.mds）。尽管我不确定读取docstring的工具通常支持标记，尤其是键入

（doc xxx）

在Clojure REPL中，只返回纯文本形式的docstring……它不需要任何方式的支持——它看起来就像纯文本一样。现在，

（doc xxx）

将继续像以前一样不加修改地将其输出。如果docstring是标记格式的，它将看起来更好，并且格式更一致。至于换行，正如您所指出的，

doc

目前似乎没有这样做。但是，请注意，大多数标记处理器将直接执行标记->标记wn“conversion”，包括换行。我可以想象，

doc

最终会这样做。在OSX上，您也可以在命令行安装lynx和markdown，然后使用clojure.java.shell发送docstring（markdown | lynx-stdin-dump）。然后你会有一个库函数，它可以从repl中很好地工作。我认为如果Clojure在这方面进行全面标准化，那会很好。如果它添加了一种标记方式，可以从函数中引用其他函数。我刚刚从ELPA更新了Clojure模式。正如你提到的，它似乎已经过时了（我找不到

clojure fill docstring

函数）。为了解决这个问题，我运行了

package list packages

，找到了一个旧的（过期的）

clojure模式

，并将其删除（用

d

标记，用

x

执行）问题解决了。

(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")
   )
  )