How should the multi-line docstrings protocol be formatted?

Question

Multiline 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 this inevitable combination of two: protocol methods? Should they just spill onto the next line with a two-position indent?

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

It looks good 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 rather strange. This is the only option that does not cause Emacs Mq to work against you, so something like this will not 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 it did not break autoformat, it looks strange to me.

So should I refuse? Should I use very short docstrings for protocol methods and maybe just include more complete documentation in the main protocol 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 also found this inconvenient, but ended up using your middle path (with a comment starting on the next line after the argument list by itself) and you won't find it looking weird. It definitely produces the best result with (doc ...) .

I originally wrote that I have no conflict between this approach and Mq , but I just did more experimentation and thought I found the problem you were raising. If I hit Mq inside the doc line, that everything I've ever done is working fine. But if I do this outside the line of the document inside the defprotocol form, yes, it will write the first lines too far. So, would you move inside the line before rescheduling it for you?

Honestly, I often look at my API document as a website created by codox these days. Therefore, I format it as Markdown and pay a little less attention to its format and readability in plain text.