1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【Tips】JSDocでHome画面(ファーストビュー)に情報や説明を表示・編集したい

Last updated at Posted at 2023-08-07

概要

受託開発企業で働く@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)した場合と比べます。
タグを使用した場合と使用しない場合のコード.png
タグを使用した場合と使用しない場合のコード2.png
上記の結果を表示した結果。
タグを使用した場合と使用しない場合のコード結果.png
※JSDocタグを書いたファイルだけHome画面に表示される。

func_1.jsに、JSDocタグを追加してみます。
タグを増やしてみたコード.png
すると、JSDocのHome画面で情報が表示されました。
タグを増やしてみたコード結果.png

補足・関連リンク

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

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?