Multiline Clojure docstrings

Question

我注意到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)))) 

这似乎奇数，因为它意味着，不同的文档字符串将具有不同的换行长度等，其需要手工维护。

是否有更好的方式来格式化多行文档？

Answer 1

如果您使用的是Emacs，请从technomancy's Github处获取clojure-mode.el，这与ELPA中的不同（我不知道为什么，都声称版本为1.11.5，也许有人可以对此进行评论？ clojure-fill-docstring这将格式化具有良好缩进和换行的文档字符串，默认绑定为C-c M-q。你做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)))) 

，并把它变成这样。

Answer 2

有没有更好的方式来格式化多行文档？

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

• 这是什么在github上使用的README文件和项目的维基（以及许多Clojure的用户使用并熟悉github上）。

• 由存在于各个Clojure的项目number.md filesofyoufind来看，这似乎是Clojure的用户之间优选的标记格式。

• 流行Marginalia文档工具呈现降价格式的文档字符串和评论（我的理解是，使用Autodoc（工具生成的clojure.org的文档）将最终呈现在文档字符串降价为好）。

• 它看起来不错，纯文本，很容易输入，不需要任何特殊的编辑器支持，而且标记最小且易于记忆。

而且，你可能已经熟悉了它，因为Stackoverflow uses it提问/回答/评论（和网站，如Reddit和各种博客评论系统使用降价为好）。

Answer 3

我同意@uvtc markdown是一个不错的选择。作为附录，我想说明的是，在REPL中使用自己的markdown文档查看功能是很简单的。以下代码假定您的类路径中有markdown-clj软件包（例如通过开发依赖），并且使用的是REPL在OSX：

(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 /文档处理特殊情况（如这一个假设，你会路过一个一个var的适当符号）。如果文件名反映“缓存”的名称空间/函数名称，而不是仅仅为每个请求重复使用相同的文件名，这可能也很好，但我为了说明的目的而保持简单。

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

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

将导致您的默认浏览器打开您的函数的文档字符串的HTMLified版本。另一个警告：如果你缩进你的多行字符串（编辑者通常会这样做），那么你的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") 
    ) 
)