概要
受託開発企業で働く@fussasyです。大規模SI開発現場でJSDocのルール作りをしていた際、分からないことはググったり、AIに尋ねて解決をしていました。ただ、各JSDocタグの解説や記載内容のベストプラクティスは検索でたくさんでてくるものの、Home画面(JSDocファーストビュー)の編集方法が出てこなくて困ったので、Tipsとして記事に残しておきます。誰かの役に立てば幸いです。
課題
Home画面(JSDocファーストビュー)にファイル名・最終更新日・ファイル解説といった情報を表示させたいです。「JSDocの書き方・出力メモ」の記事に書かれている通りに、README.mdファイルを作成してみても反映がされませんでした。(jsdocコマンド時にエラーが発生)
解決策
プログラムファイルに特定のJSDocタグを書いて対処しました。ここで紹介するタグ以外にも、Home画面に反映させられるタグはあると思います。大規模SI開発現場であれば「File」「Author」「Version」「Description」があれば、情報としては十分だと思います。また、プログラムファイル冒頭に下記のようなJSDocコメントを記載(func_1.js)しても、Home画面には反映されません。JSDocタグを記載(func_2.js)した場合と比べます。
上記の結果を表示した結果。
※JSDocタグを書いたファイルだけHome画面に表示される。
func_1.jsに、JSDocタグを追加してみます。
すると、JSDocのHome画面で情報が表示されました。
補足・関連リンク
JSDocの基本のキはコチラから
https://qiita.com/zaburo/items/c90ab1a3d7751f610d27
JSDocに関する情報は公式ドキュメントを確認すると良いです。
https://jsdoc.app/
JSDocに関する記載内容のベストプラクティスは、GoogleJSスタイルガイドラインを確認すると良いです。
https://google.github.io/styleguide/jsguide.html#jsdoc
今は記事の通りにESLintプラグインを導入し、一気にルール付けしてしまうのが主流です。(TypeScriptにも対応)
https://zenn.dev/wakamsha/articles/setup-eslint-plugin-jsdoc