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