マルチプロトコルプロトコルのドキュメントストリングはどのようにフォーマットする必要がありますか？

Question

マルチライン機能やプロトコルのドキュメンテーション文字列を簡単にフォーマットすることができます：プロトコルメソッド：2のそれは避けられない組み合わせについて

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

しかし、何を？彼らは2スペースの字下げで次の行にこぼれ落ちますか？コード内で正常に見えるが、私は(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. 

を取得し、現在は最初の行は、非常に奇妙に見える

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

。それはEmacsのMqをはあなたに対して動作するようにはならない唯一のオプションですので、このような何かが飛んでいないだろう。

(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フォーム内のドキュメント文字列の外でそれを行うと、ええ、それはあまりにも遠すぎる最初の行を押します。だから、それはあなたのために動作する前に文字列の内部に移動するだろうか？

正直言って、最近私のAPI文書は、最近codoxで作成されたWebサイトを参照しています。だから私はMarkdownとしてフォーマットしており、そのフォーマットと読みやすさにはあまり注意を払っていない。