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.