方法 : XML ドキュメント機能を使用する (C# プログラミング ガイド)
更新 : 2007 年 11 月
ドキュメント化された型の基本的な概要を次の例で示します。
使用例
// compile with: /doc:DocFileName.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
{
/// <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;
}
/// <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;
}
}
// This .xml file was generated with the previous code sample.
<?xml version="1.0"?>
<doc>
<assembly>
<name>xmlsample</name>
</assembly>
<members>
<member name="T:SomeClass">
<summary>
Class level summary documentation goes here.</summary>
<remarks>
Longer comments can be associated with a type or member
through the remarks tag</remarks>
</member>
<member name="F:SomeClass.m_Name">
<summary>
Store for the name property</summary>
</member>
<member name="M:SomeClass.#ctor">
<summary>The class constructor.</summary>
</member>
<member name="M:SomeClass.SomeMethod(System.String)">
<summary>
Description for SomeMethod.</summary>
<param name="s"> Parameter description for s goes here</param>
<seealso cref="T: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>
</member>
<member name="M:SomeClass.SomeOtherMethod">
<summary>
Some other method. </summary>
<returns>
Return results are described through the returns tag.</returns>
<seealso cref="M:SomeClass.SomeMethod(System.String)">
Notice the use of the cref attribute to reference a specific method </seealso>
</member>
<member name="M:SomeClass.Main(System.String[])">
<summary>
The entry point for the application.
</summary>
<param name="args"> A list of command line arguments</param>
</member>
<member name="P:SomeClass.Name">
<summary>
Name property </summary>
<value>
A value tag is used to describe the property value</value>
</member>
</members>
</doc>
コードのコンパイル方法
この例をコマンド ラインからコンパイルするには、次のように入力します。
csc XMLsample.cs /doc:XMLsample.xml
これで、XML ファイルの XMLsample.xml が作成されます。このファイルは、ブラウザや TYPE コマンドによって参照できます。
堅牢性の高いプログラム
XML ドキュメントは /// で始まります。新しいプロジェクトを作成すると、ウィザードによって /// で始まる行が数行表示されます。コメントの処理には、次の制限があります。
ドキュメントは、適切な XML であることが必要です。XML が整形式でない場合は警告が表示され、ドキュメント ファイルにはエラーが発生したことを表すコメントが記録されます。
開発者は、独自のタグ セットを自由に作成できます。推奨されるタグについては、関連項目を参照してください。推奨されるタグには、次のような特殊な意味を持つタグがあります。
<param> タグは、パラメータの記述に使用します。このタグを使用した場合、コンパイラはパラメータが存在するかどうか、およびすべてのパラメータがドキュメントに記述されているかどうかを検査します。検査が失敗すると、コンパイラは警告を発行します。
cref 属性をタグに追加すると、コード要素を参照できます。コンパイラは、該当するコード要素が存在するかどうかを検査します。検査が失敗すると、コンパイラは警告を発行します。コンパイラは、cref 属性に記述されている型を探すときに、using ステートメントについて考慮します。
<summary> タグは、型やメンバについての追加情報を表示するために、Visual Studio の IntelliSense で使用されています。
.gif "メモ")
メモ :XML ファイルでは、型やメンバに関する完全な情報は提供されません。たとえば、XML ファイルには型情報が含まれていません。型やメンバに関する完全な情報を得るには、ドキュメント ファイルを実際の型やメンバのリフレクションと共に使用する必要があります。