JSDoc/TSDocのコメントを改行したい

はじめに

JSDoc/TSDocでのコメント、書いてますか？
普通のコメントと違ってマウスカーソルをホバーすれば説明が表示されるようになり、ツールを使えばドキュメントを生成することもできるのでとても便利ですよね。

改行するにはバックスラッシュ

ところでこのJSDoc/TSDoc、長いコメントを書いているときに改行を含めたいことがあります。
例えばこんな感じで。

残念ながら、これだとマウスカーソルをホバーしたときやTypeDocでドキュメントを生成したときに改行が反映されません。

こういうとき、改行したい行の行末に\を置くと、

こうなります。


希望通りに改行されて表示されました。

実は行末の\で改行できるのはmarkdown方言によくある仕様（CommonMark、GFM）で、
JSDoc/TSDocはCommonMarkに準拠している（JSDoc/TSDoc）ために改行として扱われるということのようです。
個人的な好みで\の前に空白を置きましたが、これはあっても無くてもかまいません。

\はシェル上で改行のサインとしてみなさん使っていると思うので、わかりやすくて覚えやすいですね。

他の（しっくりこない）方法

他に改行を実現する方法として、

1. 末尾に空白2つ
   
2. 1行開ける
   
3. @descなどのアノテーションを使って分けてしまう
   

などがあるのですが、それぞれ

1. prettierなどのフォーマッタに末尾の空白が削除されてしまう（ignoreする必要がある）
2. 行間のスペースが広がってしまう
   
3. アノテーションなので別物として扱われてしまう
   

など、シンプルに改行したいだけという要望に対して手間がかかったり、少し違った結果になってしまいます。
また、<br />を使うとtypedocのドキュメントは改行されましたが、VSCodeのマウスホバーでは改行されません。

参考にしたURL

https://github.com/prettier/prettier/issues/6793