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

この記事では、Visual Studio が標準的な XML ドキュメント コメント構造を自動的に生成することで、クラスやメソッドなどのコード要素を文書化するのにどのように役立つかについて説明します。 コンパイル時に、ドキュメントのコメントを含む XML ファイルを生成できます。

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

Note

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

ドキュメント生成を有効にする

ドキュメント生成を有効にするには、プロジェクトのプロパティの [ビルド]>[出力] タブで、[API ドキュメントを含むファイルを生成する] チェックボックスを選択します。

既定では、.xml ファイル拡張子を持つアセンブリと同じ名前のドキュメント ファイルが、アセンブリと同じディレクトリに生成されます。 ファイルの既定以外の名前または場所を構成する場合は、XML ドキュメント ファイル パスの下の別の場所を入力または参照します。

あるいは、GenerateDocumentationFile または DocumentationFile プロパティを .csproj、.vbproj、または .fsproj ファイルに追加することもできます。 既定の名前と場所を持つドキュメント ファイルを生成するには、GenerateDocumentationFile を true に設定します。 DocumentationFile プロパティを使用して、別の名前または場所を指定します。

単独で、または GenerateDocumentationFile プロパティ セットを true に設定して DocumentationFile を使用する場合は、指定した名前と場所を持つドキュメント ファイルが生成されます。 ただし、GenerateDocumentationFile を false に設定した場合、DocumentationFile プロパティを設定してもドキュメント ファイルは生成されません。

コメントを挿入するキーボード ショートカットを有効にする

[コメント] オプションを設定すると、C# で「///」、または Visual Basic で「'''」を入力した後に XML コメント構造を自動的に挿入できます。

1. Visual Studio のメニュー バーから、[ツール]>[オプション] を選択します。
2. [オプション] ダイアログ ボックスで、[テキスト エディター]>[C#] (または [Visual Basic]) >[詳細設定] に移動します。
3. [コメント] セクションで、[\\\ (または ''') が入力されたとき、XML ドキュメント コメントを生成する] を選択または選択解除します。

XML コメントを自動挿入する

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

2. 以下のいずれかのアクションを実行します:

   • コメントの自動挿入ショートカットが有効になっている場合は、C# で「///」、または Visual Basic で「'''」を入力します。
   • [編集] メニューから、[IntelliSense]>[コメントの挿入] の順に選択します。
   • 右クリック メニューまたはコンテキスト メニューから、[スニペット]>[コメントの挿入] の順に選択します。

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

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

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

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

コードの上にカーソルを置くとクイック ヒントに表示される、コメントの XML 要素およびスタイルを使用できます。 これらの要素には、斜体または太字のスタイル、箇条書きまたは番号付きのリスト、クリック可能な cref または href リンクが含まれます。

たとえば、C# プログラム ファイルに次のコードを入力します。

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

[GetUserName] にカーソルを合わせると、クイック ヒント ウィンドウが次のように表示されます。

関連するコンテンツ

• ドキュメント コメント
• Visual Basic で XML ドキュメント
• C++ コメント
• XML に関するドキュメント (Visual C++)
• コード生成