How should multiline protocol method docstrings be formatted?

Question

Multiline function or protocol docstrings can be easily formatted:

(defn foo
  "Does a very complicated thing that I need to explain in excruciating detail.
  Firstly, this function stringifies x with the standard greeting of 'Hello'.
  Secondly, it appends the necessary exclamation point to the resulting string.
  Finally, it prints the resulting result to *out*, followed by a newline and
  the appropriate flush."
  [x]
  (println (str "Hello, " x "!")))

(defprotocol Bar
  "A retail business establishment that serves alcoholic beverages, such as
  beer, wine, liquor, cocktails, and other beverages like mineral water and soft
  drinks and often sells snack foods, like crisps or peanuts, for consumption on
  premises.")

But what about that inevitable combination of the two: protocol methods? Should they just spill onto the next line with two-space indentation?

(defprotocol Baz
  (qux [thing2 thing1] "Lorem ipsum dolor sit amet, consectetur adipiscing elit,
  sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
  minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
  commodo consequat."))

That looks fine in code, but if I call (doc qux), I get

-------------------------
user/qux
([thing2 thing1])
  Lorem ipsum dolor sit amet, consectetur adipiscing elit,
  sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
  minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
  commodo consequat.

and now the first line looks quite odd. That's the only option that doesn't cause Emacs' M-q to work against you, so something like this won't fly:

(defprotocol Baz
  (qux [thing2 thing1]
  "Lorem ipsum dolor sit amet, consectetur adipiscing elit,sed do eiusmod tempor
  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
  nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
  consequat."))

And even if that didn't break autoformat, it just looks kind of strange to me.

So should I give up? Should I only use very short docstrings for protocol methods, and maybe just include more comprehensive documentation in the protocol's main docstring?

(defprotocol Baz
  "Lorem ipsum dolor sit amet, consectetur adipiscing elit,sed do eiusmod tempor
  incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
  nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
  consequat."
  (qux [thing2 thing1] "Does a thing to thing1 depending on thing2."))

Or is there a Better Way?

Answer 1

I have found this awkward too, but end up using your middle way (with the comment starting on the next line after the argument list, by itself), and don’t find that it looks odd. It definitely produces the best looking output from (doc ...).

I originally wrote that I have no conflict between this approach and M-q, but I just did more experimentation and think I found the issue you were raising. If I hit M-q inside the doc string, which is all I ever routinely do, it works fine. But if I do it outside the doc string inside the defprotocol form, yeah, it shoves the first lines over too far. So, would moving to inside the string before reflowing it work for you?

To be honest, I most often look at my API doc as a web site produced by codox these days, though. So I am formatting it as Markdown, and paying slightly less attention to its format and readability as plain text.