方法: ドキュメント生成のための XML コメントを挿入する

  • [アーティクル]

適用対象:yesVisual Studio noVisual Studio for Mac noVisual Studio Code

Visual Studio では、クラスやメソッドなどのコード要素を文書化しやすいように、標準的な XML ドキュメント コメント構造を自動的に生成できます。 コンパイル時に、ドキュメントのコメントを含む XML ファイルを生成できます。 このオプションを有効にするには、プロジェクトのプロパティの [ビルド]>[出力] タブで、 [API ドキュメントを含むファイルを生成する] を選択します。

ヒント

ドキュメント ファイルの既定以外の名前と場所を構成する場合は、[DocumentationFile] プロパティを .csproj、 .vbproj、または .fsproj ファイルに追加します。

コンパイラによって生成された XML ファイルは、.NET アセンブリと共に配布できます。これにより、Visual Studio や他の IDE で、IntelliSense を使って型やメンバーに関する概要情報を表示できます。 さらに、DocFX や Sandcastle のようなツールを使用して XML ファイルを実行し、API リファレンスの Web サイトを生成することができます。

注意

XML ドキュメントのコメントを自動的に挿入する [コメントの挿入] コマンドは、C# と Visual Basic で使うことができます。 ただし、C++ ファイルに XML ドキュメントのコメントを手動で挿入し、コンパイル時に XML ドキュメント ファイルを生成することもできます。

コード要素の XML コメントを挿入するには

  1. メソッドなど、ドキュメント化する要素の上にテキスト カーソルを置きます。

  2. 次のいずれかの操作を行います。

    • C# では「///」と入力し、Visual Basic では「'''」と入力します

    • [編集] メニューから、 [IntelliSense]>[コメントの挿入] の順に選択します

    • コード要素の前面またはすぐ上に表示される右クリック メニューまたはコンテキスト メニューから、 [スニペット]>[コメントの挿入] の順に選択します

    すぐに、XML テンプレートがコード要素の上に生成されます。 たとえば、メソッドのコメントを生成すると、<summary> 要素、各パラメーターの <param> 要素、および戻り値を文書化するための <returns> 要素が生成されます。

    XML comment template - C#

    XML comment template - Visual Basic

  3. 各 XML 要素の説明を入力し、コード要素を完全に文書化します。

    Screenshot showing the completed comment.

要素の上にカーソルを置くとクイック ヒントに表示される、XML コメントのスタイルを使用できます。 これらのスタイルには、斜体、太字、箇条書き、クリック可能なリンクなどがあります。

Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.

注意

/// (C#) または ''' (Visual Basic) を入力した後で XML ドキュメントのコメントを切り替えるためのオプションがあります。 メニュー バーから [ツール]>[オプション] の順に選択して、 [オプション] ダイアログ ボックスを開きます。 次に、[テキスト エディター]>[C#] (または [Visual Basic]) >[詳細] に移動します。 [エディターのヘルプ] セクションで、 [XML ドキュメントを生成する] オプションを探します。

参照