2019 年末の Visual Studio 16.4 のアップデートで、inheritdoc タグに対応しました。その他、気になったところをメモする記事です。
詳細は Microsoft のブログにて
新しい機能(でメモしたところ)
- inhertdoc タグ(XML Documentation タグの追加)
- 「基本へ移動」
- タブレイアウトの設定
1. inheritdoc とは?
XML Documentation のタグのひとつです。
コード内のドキュメント コメントは、コード補完(インテリセンスの補助)によってコーディングをサポートしたり、/doc コマンド ライン オプションで指定した名前のファイルに XML 形式で出力したりできます。
さて、そのタグのひとつである inheritdoc
タグの機能は、継承可能なクラスまたは実装可能なインタフェースから、ドキュメントを継承(コピー)する機能です。この機能により、汎用的なコメントを継承ツリーの上位に記述することで、継承(コピー)したドキュメントを使いまわすことができます。1
つまり、
基本になる型/メンバーと共通のコメントを継承することで、API の文書化に必要な作業コストを抑えることができます。2
補足
inheritdoc は、visual studio のコード補完にこれまで表示されませんでしたが、JAVA でも実装されているコメント機能です。
C# でも古くから Sandcastle は対応している機能でしたが、今回になってようやくコード補完でもサポートされるようになりました。
実際につかってみる
こんな感じで、interface のコメントを継承したクラスでも interface のコメントが表示されます。それにクラスの利用先でもコメントが表示されます。
通常のコメントとまったく同じ雰囲気ですね。
2.「基本へ移動」
わかりづらい名前ですが、「Alt + Home」キー、または、右クリックメニューから「基本へ移動」を選択することで、継承元(定義先)にジャンプできるようになりました。
これは、かなり便利なのでショートカットキーを覚えたいところ。
英語だとこんな感じで書いてあります。
The Go To Base command is available on the context (right-click) menu or you can type (Alt+Home) on the element you want to navigate through the inheritance hierarchy.
「‘Tis the Season for the Visual Studio 2019 v16.4 Release - .NET Productivity」より
3. タブレイアウトの設定
これも単純で、これまでヘッダーのように表示されていたタブレイアウトが左右に移動できるようになっています。
地味に便利で、検索したところたくさんの(不要な)タグが開いてしまったときなんかは、左右のタブレイアウトのほうが整理しやすそう。
サンプル
「Samples」に今回のコード「InheritdocTest」を追加しました。
参考
- 作者:BillWagner
- 発売日: 2018/09/05
- メディア: Kindle版
リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)
- 作者:Dustin Boswell,Trevor Foucher
- 発売日: 2012/06/23
- メディア: 単行本(ソフトカバー)