应该如何格式化多行协议方法文档字符串？

Question

多行功能或协议文档字符串可以轻松格式化:

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

但那两种不可避免的组合怎么样:协议方法呢？它们应该只用两个空格缩进到下一行吗？

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

这在代码中看起来很好,但如果我打电话(doc qux),我会得到

-------------------------
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.

现在第一行看起来很奇怪.这是唯一不会导致Emacs M-q对你不利的选择,所以这样的事情不会飞:

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

即使这并没有打破autoformat,它对我来说只是有点奇怪.

我应该放弃吗？我是否应该只使用非常短的文档字符串进行协议方法,并且可能只是在协议的主文档字符串中包含更全面的文档？

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

或者,还有更好的方法？

Answer 1

我也发现这很尴尬，但最终使用了中间方式（注释本身在参数列表之后的下一行开始），并且 don\xe2\x80\x99t 发现它看起来很奇怪。它绝对会产生最好看的输出(doc ...)。

\n\n

我最初写道，这种方法和 之间没有冲突M-q，但我只是做了更多实验，并认为我发现了您提出的问题。如果我点击文档字符串M-q 内部（这是我经常做的事情），它就可以正常工作。但是，如果我在表单内的文档字符串之外执行此操作defprotocol，是的，它会将第一行推得太远。那么，在回流之前移动到字符串内部对您有用吗？

\n\n

老实说，我最常将 API 文档视为codox制作的网站老实说，现在因此，我将其格式化为 Markdown，并稍微减少对纯文本格式和可读性的关注。

\n