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

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

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

注

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

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

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

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

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

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

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

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

1. Visual Studio のメニュー バーで、[ツール] >[オプション] を選択します。
2. [ オプション ] ダイアログ ボックスで、[ テキスト エディター>C# (または Visual Basic) >Advanced) に移動します。
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++)
• コード生成