방법: 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 명령줄을 입력하면 됩니다.

이 명령을 실행하면 XML 파일 XMLsample.xml이 만들어집니다. 이 파일은 브라우저 또는 워드 프로세서에서 볼 수 있습니다.

또는 솔루션 탐색기에서 프로젝트 이름을 마우스 오른쪽 단추로 클릭한 다음 속성을 클릭합니다. 빌드 탭의 출력 섹션에서 XML 문서 파일을 선택한 다음 .xml 파일의 이름을 입력합니다.

강력한 프로그래밍

XML 문서는 ///로 시작합니다. 새 프로젝트를 작성할 때 IDE는 몇 개의 /// 줄을 추가합니다. 이러한 주석 처리에는 다음과 같은 제한이 있습니다.

• 이 문서는 반드시 제대로 구성된 XML이어야 합니다. XML을 제대로 구성하지 않으면 경고가 생성되고 문서 파일에 오류가 발생하였음을 알리는 주석이 포함됩니다.

• 개발자는 고유한 태그 집합을 만들 수 있습니다. 하지만 다음 예제에 설명된 것처럼 특별한 의미를 갖는 권장 태그 집합(이 항목의 참고 항목 단원 참조)이 있습니다.

  • <param> 태그는 매개 변수를 설명하는 데 사용됩니다. 이 태그를 사용하면 컴파일러가 매개 변수의 존재 그리고 모든 매개 변수가 문서에서 설명되어 있는지 확인합니다. 확인이 실패하면 컴파일러에 경고가 발생합니다.

  • cref 특성은 모든 태그에 연결되어 코드 요소에 대한 참조를 제공할 수 있습니다. 컴파일러는 코드 요소가 존재하는지 확인합니다. 확인이 실패하면 컴파일러에 경고가 발생합니다. 컴파일러는 cref 특성에 설명된 형식을 찾을 때 모든 using 문을 고려합니다.

  • <summary> 태그는 Visual Studio 내의 IntelliSense에 의해 사용되어 형식이나 멤버에 관한 추가 정보를 표시합니다.

    참고

    XML 파일은 형식 및 멤버에 대한 완전한 정보를 제공하지 않습니다. 예를 들어 XML 파일에는 어떠한 형식 정보도 포함되지 않습니다. 형식이나 멤버에 대한 전체 정보를 보려면 실제 형식이나 멤버에 반영한 문서 파일을 사용해야 합니다.

참고 항목

참조

/doc(C# 컴파일러 옵션)

XML 문서 주석(C# 프로그래밍 가이드)

개념

C# 프로그래밍 가이드

변경 기록