方法 : XML ドキュメント機能を使用する (C# プログラミング ガイド)

更新 : 2011 年 4 月

XML ドキュメントでは、コードを効率的に文書化できます。 基本的な概要を次の例に示します。

使用例

// If compiling from the command line, compile with: /doc:YourFileName.xml

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.</remarks>
public class TestClass : TestInterface
{
    /// <summary>
    /// Store for the name property.</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here.
    }

    /// <summary>
    /// Name property. </summary>
    /// <value>
    /// A value tag is used to describe the property value.</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here.</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method. </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments.</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here.
        return 0;
    }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

前の例で生成された .xml ファイルを次に示します。 インターフェイス定義のコメントは、そのインターフェイスを実装するクラスに含まれていることに注意してください。

コードのコンパイル

この例をコンパイルするには、コマンド ライン csc XMLsample.cs /doc:XMLsample.xml を入力します。

このコマンドにより、XMLsample.xml XML ファイルが作成されます。このファイルは、ブラウザーまたはワード プロセッサで表示できます。

別の方法として、ソリューション エクスプローラーでプロジェクト名を右クリックし、[プロパティ] をクリックします。 [ビルド] タブで、[出力] セクションの [XML ドキュメント ファイル] を選択し、.xml ファイルの名前を入力します。

信頼性の高いプログラミング

XML ドキュメントは /// で始まります。 新しいプロジェクトを作成すると、IDE によって /// で始まる行が数行追加されます。 これらのコメントの処理には、次の制限があります。

• ドキュメントは、適切な XML であることが必要です。 XML が整形式でない場合は警告が生成され、ドキュメント ファイルにはエラーが発生したことを示すコメントが記録されます。

• 開発者は、独自のタグ セットを作成できます。 ただし、次の例に示すように、特殊な意味を持つ推奨タグ セットがあります (このトピックの「参照」を参照してください)。

  • <param> タグは、パラメーターの記述に使用します。 このタグを使用した場合、コンパイラはパラメーターが存在すること、およびすべてのパラメーターがドキュメントに記述されていることを検査します。 検査に失敗した場合、コンパイラは警告を発行します。

  • cref 属性をタグに追加すると、コード要素を参照できます。 コンパイラは、そのコード要素が存在することを検査します。 検査に失敗した場合、コンパイラは警告を発行します。 コンパイラは、cref 属性に記述されている型を探すときに、using ステートメントについて考慮します。

  • <summary> タグは、型やメンバーについての追加情報を表示するために、Visual Studio の IntelliSense で使用されています。

    注意

    XML ファイルでは、型またはメンバーに関する完全な情報は提供されません。 たとえば、XML ファイルには型情報は含まれていません。 型やメンバーに関する完全な情報を得るには、ドキュメント ファイルを実際の型やメンバーのリフレクションと共に使用する必要があります。

参照

参照

/doc (C# コンパイラ オプション)

XML ドキュメント コメント (C# プログラミング ガイド)

概念

C# プログラミング ガイド

履歴の変更