Wyciągi Multiline Clojure

Question

Zauważyłem, że doclety wielowierszowe Clojure wydają się być ręcznie formatowane w większości przypadków, w tym te w clojure.core. Przykład z 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)))) 

Wydaje dziwne, ponieważ oznacza to, że różne docstrings mają różne długości przewodów oblewania itd, które muszą być ręcznie utrzymywana.

Czy istnieje lepszy sposób formatowania docletów wieloliniowych?

Answer 1

Jeśli używasz Emacsa, pobierz clojure-mode.el z technomancy's Github, który różni się od tego w ELPA (nie wiem dlaczego, obie twierdzą, że jest wersja 1.11.5, może ktoś może to skomentować?), Ale zawiera clojure-fill-docstring, które sformatuje docstrukcje z ładnym wcięciem i linewrowaniem, domyślnie powiązane z C-c M-q.

potrwa to:

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

i przekształcić go w ten sposób:

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

po wykonaniu C-c M-q z punktu wewnątrz docstring.

Answer 2

Czy istnieje lepszy sposób formatowania docletów wieloliniowych?

Moja sugestia polega na użyciu formatowania Markdown w swoich docstrings. Oto kilka powodów:

• to, co jest wykorzystywane w github w README oraz wiki projektu (a wielu użytkowników Clojure użyciu i są zaznajomieni z github).

• sądząc po numberof.md filesyoufind obecne w różnych projektach Clojure, wydaje się być preferowany format znaczników wśród użytkowników Clojure.

• popularne narzędzie Marginalia doc czyni przecenowych sformatowany docstrings i Komentarze (i moje rozumienie jest Autodoc (narzędzie wykorzystywane do generowania docs na clojure.org) będzie ostatecznie uczynić przecen w docstrings również).

• Wygląda dobrze jak zwykły tekst, jest łatwy do wpisania, nie wymaga specjalnej obsługi redaktora, a znaczniki są minimalne i łatwe do zapamiętania.

Ponadto, prawdopodobnie jesteś już zaznajomiony z nim, ponieważ Stackoverflow uses it do pytania/odpowiedzi/komentarze (i stron takich jak różne systemy blogu komentując reddit i używać Markdown również).

Answer 3

Zgadzam się z @uvtc, że obniżka jest dobrym wyborem. Jako dodatek, chciałbym zauważyć, że generowanie własnej funkcji podglądu dokumentacji do wykorzystania w REPL jest banalne. Poniższy kod zakłada, że ​​masz pakiet markdown-clj na ścieżce klas (np.poprzez zależności dev) i używasz rEPL w 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") 
    ) 
) 

Czasami warto spojrzeć na źródło clojure.repl/doc obsłużyć szczególnych przypadkach (np ten zakłada będziesz przechodzącą w odpowiedni symbol dla var). Dobrze byłoby, gdyby nazwa pliku odzwierciedlała przestrzeń nazw/funkcję dla "buforowania", zamiast tylko ponownego używania tej samej nazwy pliku dla każdego żądania ... ale zachowuję to dla uproszczenia w celach ilustracyjnych.

Komenda OSX open po prostu prosi system operacyjny o otwarcie pliku poprzez wykrycie jego typu. Tak więc:

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

spowoduje, że domyślna przeglądarka otworzy wersję HTML dokumentu funkcji.

Jeszcze jedno zastrzeżenie: jeśli wcinasz swój ciąg wielowierszowy (który zwykle robią redaktorzy), to twój MD może skończyć się dziwactwem (np. Listy wypunktowane mogą zagnieździć się w sposób, który nie jest zamierzony). Jednym ze sposobów rozwiązania tego problemu jest usunięcie tego. Na przykład:

(defn boo 
    " 
    # Title 
    My thing 

    * Item one 
    * Item two 
    " 
    [args] ...) 

a następnie zmodyfikować funkcję OpenDoc najpierw zastosować lewy wykończenia:

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