JSDoc の @deprecated を TypeScriptと併用する

フロントエンドエンジニアの茶木です。
コードエディタは Visual Studio Code を使っています。

React x TypeScript では、エディタ上で型情報のヒントがうまく機能するため、JSDoc を意識して利用することはなかったのですが、先日、JSDoc の @deprecated が便利と感じたので、 TypeScript との併用を視点に当記事を書きました。

非奨励 @deprecated をマークする

/**
 * @deprecated
 */
export const methodV1 = (): void => {

非奨励になったメソッドに JSDoc の @deprecated をつけておくと、エディタで警告されるようになります。Visual Studio Code では、使用箇所に打ち消し線が引かれるようになり、使用箇所に気がつけるようになります。

さらに、@deprecated のあとにコメントをつけられます。

/**
 * @deprecated methodV2 を使用すること
 */
export const methodV1 = (): void => {

使用箇所に打ち消し線が引かれるのはもちろん、コメントは、エディタのヒントに表示されます。代替メソッドの記載や非奨励の背景、参考リンクなどを記載しておけば、複数人で進めるプロジェクトに良い影響があると考えます。

• 改修時に、作業箇所にある非奨励メソッドを差し替える
• 機能追加時に、非奨励メソッドをうっかり混ぜ込まない

非奨励メソッドの使用を減らしていく方向にプロジェクトのメンバーの行動をやんわり誘導していけそうです。

おわりに

最後に、TypeScript と併用する JSDoc の他のタグの使用感について述べます。

引数や戻り値、関数の説明を JSDoc で書く必要は薄い

引数や戻り値を @param や @return で書いておくと、エディタにヒントが表示され便利でした。しかしTypeScript による型定義の記載をすることでも引数や戻り値の型がヒントで確認できるため、あまりメリットは感じられません。また、@description による関数自体の説明もコードから読み取れるように書くほうが重要と考えます。

自動生成では重宝する

しかし自動生成の場合は少し違います。たとえば、OpenAPI など JSON や YAML で書き、ジェネレートされた JavaScript ファイルに、JSDoc が含まれていると便利です。私見ですが、自動生成される mock API はコードリーディングはあまり重要ではなく、自然言語での説明があるのは助かります。

使用例を書くなら @example を使うとコードヒントにでる

@example も @deprecated 同様にコードヒント上で重宝します。 @example は 使用例を示すのに使います。型情報やメソッド名から使用方法が類推しにくいときに有効だと考えます。

/**
 * @example methodV2({ ...defaultData, updatedDate: number }})
 */
export const methodV2 = (data: V2Data) => {

@example に記載した使用例は、通常のコメントと違い、メソッドを呼び出す際に（さりげなく）コードヒントで表示されるため、定義元のファイルを確認しに行かなくても良い点が挙げられます。