📝

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

2024/03/11に公開

はじめに

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

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

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

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

こういうとき、改行したい行の行末に\を置くと、
2行にわたるコメントの1行目の末尾にバックスラッシュを置いた様子
こうなります。
2行にわたるコメントが改行された様子
TypeDocのドキュメント上でコメントが改行されている様子
希望通りに改行されて表示されました。

実は行末の\で改行できるのはmarkdown方言によくある仕様(CommonMarkGFM)で、
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

Discussion