多行Clojure文档字符串

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,请clojure-mode.el从technomancy的Github中获取,这与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-qdocstring中使用你的观点之后.

Answer 2

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

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

• 它是在README和项目wiki中使用的github(许多Clojure用户使用并熟悉github).

• 根据您在各种Clojure项目中找到的.md文件的数量 来 判断,它似乎是Clojure用户中首选的标记格式.

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

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

此外,您可能已经熟悉它,因为Stackoverflow将其用于问题/答案/评论(而reddit和各种博客评论系统等网站也使用Markdown).