Multiline Clojure docstrings

Question

I've noticed that Clojure multiline docstrings seem to be manually formatted in most cases, including the ones in clojure.core. Example from 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)))) 

This seems odd, as it means that different docstrings will have different line wrap lengths etc. which need to be manually maintained.

Is there a better way to format multiline docstrings?

Answer 1

If you're using Emacs, grab clojure-mode.el from technomancy's Github, which differs from the one in ELPA (I don't know why, both claim to be version 1.11.5, maybe someone can comment on that?) but includes clojure-fill-docstring which will format docstrings with nice indentation and linewrapping, bound by default to C-c M-q.

It will take this:

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

and turn it into this:

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

after you do C-c M-q with your point inside the docstring.