27

我注意到在大多数情况下，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))))

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

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

4

3 回答 3

14

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

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

  • 它是 github 在 README 和项目 wiki 中使用的内容（许多 Clo​​jure 用户使用并熟悉 github）。

  • 从您在各种 Clojure 项目中发现的.md 文件的数量 来看，它似乎是 Clojure 用户首选的标记格式。

  • 流行的Marginalia doc 工具呈现 markdown 格式的文档字符串和注释（我的理解是Autodoc（用于在 clojure.org 生成文档的工具）最终也会在文档字符串中呈现 markdown）。

  • 它看起来像纯文本一样好，易于键入，不需要任何特殊的编辑器支持，并且标记最少且易于记忆。

此外，您可能已经熟悉它，因为Stackoverflow 将它用于问题/答案/评论（reddit 和各种博客评论系统等网站也使用 Markdown）。

于 2012-05-23T05:04:14.850 回答
14

如果您使用的是 Emacs，请从 technomancy 的 Github 中获取clojure-mode.el，它与 ELPA 中的不同（我不知道为什么，两者都声称是 1.11.5 版本，也许有人可以对此发表评论？）但包括clojure-fill-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))))

在你C-c M-q在文档字符串中处理你的观点之后。

于 2012-05-23T16:03:24.103 回答
2

我同意@uvtc 的观点，即降价是一个不错的选择。作为附录，我想指出，生成您自己的 Markdown 文档查看功能以在 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 符号）。让文件名反映“缓存”的命名空间/函数名也可能很好，而不是仅仅为每个请求重用相同的文件名......但为了说明目的，我保持简单。

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

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")
   )
  )
于 2015-06-04T19:24:33.793 回答