[C#, Visual Studio]ドキュメントコメント(/// <summary>のやつ)に関わる概念の整理(何となく使っている状態から一歩進めたい)

はじめに

Visual StudioでC#を書いているとき、クラスやメソッドの上に/// <summary>を書くとVisual StudioのIntelliSenseがいい感じにコメント内容を表示してくれます。

/// <summary>
/// これがドキュメンテーションコメントです
/// </summary>
public static void Hoge()

こう書くと、Visual Studioにおいて、メソッドの説明に入力したコメントが表示されます。

クラスやメソッドの上に///を書くと自動的にsummaryが挿入されるので、これまで自分は何も考えずに便利だなあと思って使っていました。
この機能についてちゃんと調べてみて、公式ドキュメントで便利な使い方を見つけたのですが、その中の<see>と<seealso>が同じっぽいけど何が違うんだろうと疑問でした。

以下の画像のように、seeやseealsoを使うとクラスやメソッドに対するリンクにすることができます(クリックでリンク先に飛べます)。この形式だと(コメント内に文字列として書く場合とは異なり)VS上で参照として機能するため便利です(画像の「2件の参照」はseeとseealsoのcref分です)。

この疑問をきっかけに色々調べていると、この機能について自分の中でドキュメントコメントに関する色々な概念が整理されていないことに気が付いたので、この記事でまとめてみます。

ドキュメントコメントとは何かの整理

まず、公式ドキュメントが色々とあったので、いくつか貼っておきます。

(1)XML ドキュメント コメント
(2)C# ドキュメント コメントとして推奨される XML タグ
(3)ドキュメント コメント(C# 言語仕様)

以下、ドキュメントコメントに対して自分の中でごちゃっと認識していた概念を分解して書いてみます。

・XML形式でコメントを書いている
あくまでコメントを書いているだけなので、C#、Visual Studioに関係なくXML形式でコメントを書きたいなら書けるわけです。この(何もしなければ)単なるコメントを、Visual Studio、C#それぞれで便利に使っているようです。

・Visual Studioの機能としてクラス・メソッドの説明として表示される
Visual Studioの便利機能として、メソッド・クラスの上に///を入力すると<summary>一式が自動挿入され、それがIntelliSenseに表示されます。
気軽に自動挿入して入るのが一番身近な接点のため、VSの機能っぽい気がしますが、次に書く通りC#側でも用途があるようです。

・C#の機能として、XMLドキュメントコメントをドキュメント化することができる。
これは自分が全く把握していない側面でした。C#の言語仕様として、ルールに従ってドキュメントコメントを記載するとドキュメントを生成できるとのことです。ドキュメントの(3)に詳しいです。

さいごに seeとseealsoの違い

ここまでまとめると、seeとseealsoの違いが分かるようになりました。

• seeもseealsoも、VSのIntelliSense上では同じように動くので、このかぎりではちがいはなさそう
• C#によってドキュメントコメントをドキュメント化した際に、seeとseealsoは異なる形でドキュメント化される

ということのようです。