次の方法で共有


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

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

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

Note

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

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

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

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

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

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

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

単独で、または GenerateDocumentationFile プロパティ セットを true に設定して DocumentationFile を使用する場合は、指定した名前と場所を持つドキュメント ファイルが生成されます。 ただし、GenerateDocumentationFilefalse に設定した場合、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] にカーソルを合わせると、クイック ヒント ウィンドウが次のように表示されます。

クリック可能なリンク、番号付きのリスト、および斜体と太字の書式設定のスタイル タグを含む完了したコメントを示すスクリーンショット。