방법: 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 파일은 형식과 멤버에 대한 전체 정보를 제공하지 않습니다. 예를 들어, 형식 정보가 포함되지 않을 수 있습니다. 형식이나 멤버에 대한 전체 정보를 보려면 실제 형식이나 멤버에 반영한 문서 파일을 사용해야 합니다.