Q:

Multiline Clojure docstrings

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?

A:

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.

A:

Is there a better way to format multiline docstrings?

My suggestion is to use Markdown formatting in your docstrings. Here are some reasons why:

it's what's used at github in README's and project wikis (and many Clojure users use and are familiar with github).
judging by the number of .md files you find present in various Clojure projects, it appears to be a preferred markup format among Clojure users.
the popular Marginalia doc tool renders markdown-formatted docstrings and comments (and my understanding is that Autodoc (the tool used to generate the docs at clojure.org) will eventually render markdown in docstrings as well).
It looks good as plain text, is easy to type, doesn't require any special editor support, and the markup is minimal and easy to remember.

Also, you're probably already familiar with it, since Stackoverflow uses it for questions/answers/comments (and sites like reddit and various blog commenting systems use Markdown as well).

