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＆＃39; 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."))

即使这并没有破坏自动生成，但对我来说这看起来有点奇怪。

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

(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

我也发现了这个尴尬，但最后使用你的中间方式（在参数列表之后的下一行开始的评论，本身），并且发现它看起来很奇怪。它肯定会产生(doc ...)的最佳效果。

我最初写道，这种方法与 M-q 之间没有冲突，但我只是做了更多的实验，并认为我发现了你提出的问题。如果我在里面找到 M-q 文件字符串，这是我经常做的事情，它可以正常工作。但是，如果我在defprotocol形式的doc字符串之外进行，是的，它将第一行推到了太远的位置。那么，在回流之前它会移动到字符串内部吗？

说实话，我经常将我的API文档视为codox最近生成的网站。因此我将其格式化为Markdown，并将其格式和可读性略微关注为纯文本。

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

1 个答案: