C# 문서 주석에 대한 권장 XML 태그

C# 문서 주석은 XML 요소를 사용하여 출력 문서의 구조를 정의합니다. 이 기능의 한 가지 결과는 문서 주석에 유효한 XML을 추가할 수 있다는 것입니다. C# 컴파일러는 이러한 요소를 출력 XML 파일에 복사합니다. 주석에 유효한 XML(유효한 HTML 요소 포함)을 사용할 수 있지만 여러 가지 이유로 코드를 문서화하는 것이 좋습니다.

이어서 몇 가지 권장 사항과 일반적인 사용 사례 시나리오, 그리고 C# 코드에서 XML 문서 태그를 사용할 때 알아야 할 내용을 살펴봅니다. 문서 주석에 태그를 넣을 수 있지만 이 문서에서는 가장 일반적인 언어 구문에 권장되는 태그를 설명합니다. 모든 경우에 다음 권장 사항을 준수해야 합니다.

• 일관성을 보장하기 위해 모든 공개 형식과 public 멤버를 문서화해야 합니다.
• Private 멤버는 XML 주석을 사용하여 문서화할 수도 있습니다. 그러나 이렇게 하면 라이브러리의 내부(잠재적으로 기밀) 작업이 표시됩니다.
• 최소한 형식과 해당 멤버에는 <summary> 태그가 있어야 합니다.
• 문서 텍스트는 마침표로 끝나는 전체 문장을 사용하여 기록되어야 합니다.
• Partial 클래스는 완전히 지원되고 문서 정보는 각 형식의 단일 항목에 연결됩니다. partial 멤버의 두 선언에 문서 주석이 있는 경우, 구현 선언에 대한 주석이 출력 XML에 기록됩니다.

XML 문서는 ///로 시작합니다. 새 프로젝트를 만드는 경우 템플릿에서 몇 개의 시작 /// 줄을 자동으로 넣습니다. 이러한 주석의 처리에는 몇 가지 제한이 있습니다.

• 문서는 잘 구성된 XML이어야 합니다. XML이 잘 구성되지 않은 경우 컴파일러에서 경고를 생성합니다. 문서 파일에는 오류가 발생했다고 말하는 주석이 포함됩니다.
• 권장 태그 중 일부는 특별한 의미가 있습니다.
  • <param> 태그는 매개 변수를 설명하는 데 사용됩니다. 사용되는 경우 컴파일러는 매개 변수가 있고 모든 매개 변수가 문서에서 설명되었는지 확인합니다. 확인에 실패하면 컴파일러가 경고를 실행합니다.
  • cref 특성을 태그에 연결하여 코드 요소를 참조할 수 있습니다. 컴파일러에서 이 코드 요소가 있는지 확인합니다. 확인에 실패하면 컴파일러가 경고를 실행합니다. 컴파일러는 cref 특성에 설명된 형식을 찾을 때 모든 using 지시문을 따릅니다.
  • <summary> 태그는 Visual Studio 내의 IntelliSense에서 형식 또는 멤버에 대한 추가 정보를 표시하는 데 사용됩니다.

    참고 항목

    XML 파일은 형식 및 멤버에 대한 전체 정보를 제공하지 않습니다(예: 형식 정보가 포함되지 않음). 형식 또는 멤버에 대한 전체 정보를 가져오려면 실제 형식 또는 멤버에 대한 리플렉션과 함께 문서 파일을 사용하세요.

• 개발자는 각자 고유한 태그 집합을 만들 수 있습니다. 컴파일러는 이러한 태그를 출력 파일에 복사합니다.

권장 태그 중 일부는 모든 언어 요소에서 사용할 수 있습니다. 나머지는 좀 더 특수한 용도로 사용할 수 있습니다. 마지막으로 일부 태그는 문서의 텍스트 서식을 지정하는 데 사용됩니다. 이 문서에서는 용도에 따라 구성된 권장 태그에 대해 설명합니다.

컴파일러는 다음 목록에서 *가 있는 요소의 구문을 확인합니다. Visual Studio는 컴파일러에서 확인된 태그와 다음 목록에서 **가 있는 모든 태그에 IntelliSense를 제공합니다. 여기에 나열된 태그 외에도 컴파일러와 Visual Studio는 <b>, <i>, <u>, <br/>, <a> 태그의 유효성을 검사합니다. 컴파일러는 또한 사용되지 않는 HTML인 <tt>의 유효성을 검사합니다.

• 여러 요소에 사용되는 일반 태그 - 이 태그는 모든 API에 대한 최소 세트입니다.
  • <summary>: 이 요소의 값은 Visual Studio의 IntelliSense에 표시됩니다.
  • <remarks> **
• 멤버에 사용되는 태그 - 메서드 및 속성을 문서화할 때 사용됩니다.
  • <returns>: 이 요소의 값은 Visual Studio의 IntelliSense에 표시됩니다.
  • <param> *: 이 요소의 값은 Visual Studio의 IntelliSense에 표시됩니다.
  • <paramref>
  • <exception> *
  • <value>: 이 요소의 값은 Visual Studio의 IntelliSense에 표시됩니다.
• 문서 출력 서식 지정 - 문서를 생성하는 도구에 대한 서식 지정 지침을 제공합니다.
  • <para>
  • <list>
  • <c>
  • <code>
  • <example> **
• 문서 텍스트 다시 사용 - XML 주석을 더 쉽게 다시 사용할 수 있는 도구를 제공합니다.
  • <inheritdoc> **
  • <include> *
• 링크 및 참조 생성 - 다른 문서에 대한 링크를 생성합니다.
  • <see> *
  • <seealso> *
  • cref
  • href
• 제네릭 형식 및 메서드에 대한 태그 - 제네릭 형식 및 메서드에서만 사용됩니다.
  • <typeparam> *: 이 요소의 값은 Visual Studio의 IntelliSense에 표시됩니다.
  • <typeparamref>

참고 항목

네임스페이스에는 문서 주석을 적용할 수 없습니다.

문서 주석의 텍스트에 꺾쇠괄호를 표시하려면 각각 < 및 >인 < 및 >의 HTML 인코딩을 사용합니다. 이 인코딩은 다음 예제에서 확인할 수 있습니다.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

일반 태그

<요약>

<summary>description</summary>

<summary> 태그를 사용하여 형식 또는 형식 멤버를 설명해야 합니다. <remarks>를 사용하여 형식 설명에 보충 정보를 추가할 수 있습니다. cref 특성을 사용하면 DocFX 및 Sandcastle 등의 문서화 도구를 통해 코드 요소의 문서화 페이지에 대한 내부 하이퍼링크를 만들 수 있습니다. <summary> 태그의 텍스트는 IntelliSense 및 개체 브라우저 창에 표시됩니다.

<설명>

<remarks>
description
</remarks>

<remarks> 태그는 형식 또는 형식 멤버에 대한 정보를 추가하여 <summary>로 지정된 정보를 보완하는 데 사용됩니다. 이 정보는 개체 브라우저 창에 표시됩니다. 이 태그는 더 긴 설명을 포함할 수 있습니다. Markdown에 CDATA 섹션을 사용하면 쓰기가 더욱 편리해집니다. docfx 같은 도구는 CDATA 섹션에서 Markdown 텍스트를 처리합니다.

문서 멤버

<returns>

<returns>description</returns>

<returns> 태그는 메서드 선언의 주석에서 반환 값을 설명하는 데 사용해야 합니다.

<param>

<param name="name">description</param>

• name: 메서드 매개 변수의 이름입니다. 이름을 따옴표(")로 묶습니다. 매개 변수의 이름은 API 시그니처와 일치해야 합니다. 하나 이상의 매개 변수가 적용되지 않으면 컴파일러에서 경고가 발생합니다. 컴파일러는 name 값이 메서드 선언의 형식 매개 변수와 일치하지 않는 경우에도 경고를 표시합니다.

<param> 태그는 메서드의 매개 변수 중 하나를 설명하기 위해 메서드 선언에 대한 주석에서 사용해야 합니다. 여러 매개 변수를 문서화하려면 여러 개의 <param> 태그를 사용합니다. <param> 태그에 대한 텍스트는 IntelliSense, 개체 브라우저, 코드 주석 웹 보고서에 표시됩니다.

<paramref>

<paramref name="name"/>

• name: 참조할 매개 변수의 이름입니다. 이름을 따옴표(")로 묶습니다.

<paramref> 태그를 사용하면 <summary> 또는 <remarks> 블록 등의 코드 주석에 포함된 단어가 매개 변수를 참조함을 나타낼 수 있습니다. XML 파일을 처리하여 굵게, 기울임꼴 글꼴 등의 고유한 방식으로 이 단어에 서식을 지정할 수 있습니다.

<exception>

<exception cref="member">description</exception>

• cref = “member”: 현재 컴파일 환경에서 사용할 수 있는 예외에 대한 참조입니다. 컴파일러는 지정된 예외가 있으며 member를 출력 XML의 정식 요소 이름으로 변환하는지 확인합니다. member는 따옴표(") 안에 표시되어야 합니다.

<exception> 태그를 사용하면 throw할 수 있는 예외를 지정할 수 있습니다. 이 태그는 메서드, 속성, 이벤트 및 인덱서에 대한 정의에 적용할 수 있습니다.

<value>

<value>property-description</value>

<value> 태그를 사용하면 속성이 나타내는 값을 설명할 수 있습니다. Visual Studio .NET 개발 환경에서 코드 마법사를 통해 속성을 추가하면 새 속성에 대한 <summary> 태그가 추가됩니다. 그런 다음, <value> 태그를 수동으로 추가하여 속성이 나타내는 값을 설명합니다.

문서 출력 서식 지정

<p>ara

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

<para> 태그는 <summary>, <remarks>, <returns> 등의 태그 내에 사용되어 텍스트에 구조를 추가할 수 있게 합니다. <para> 태그는 이중 공백 단락을 만듭니다. 단일 공백 단락을 원하는 경우 <br/> 태그를 사용합니다.

<목록>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

<listheader> 블록은 테이블 또는 정의 목록의 머리글 행을 정의하는 데 사용됩니다.

테이블을 정의할 때:

• 제목에 term 항목만 제공하면 됩니다.
• 목록의 각 항목은 <item> 블록을 사용하여 지정됩니다. 각 item에 대해 description의 항목만 제공하면 됩니다.

정의 목록을 만들 때:

• 제목에 term 항목을 제공해야 합니다.
• 목록의 각 항목은 <item> 블록을 사용하여 지정됩니다. 각 item에는 term 및 description이 모두 포함되어야 합니다.

목록 또는 테이블에 <item> 블록을 필요한 개수만큼 포함할 수 있습니다.

<c>

<c>text</c>

<c> 태그를 사용하면 설명 내의 텍스트를 코드로 표시해야 함을 지정할 수 있습니다. 여러 줄을 코드로 표시하려면 <code>를 사용합니다.

<code>

<code>
    var index = 5;
    index++;
</code>

<code> 태그는 여러 코드 줄을 나타내는 데 사용됩니다. <c>는 설명 내의 한 줄 텍스트가 코드로 표시되어야 함을 나타내는 데 사용합니다.

<예제>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

<example> 태그를 사용하면 메서드 또는 기타 라이브러리 멤버를 사용하는 방법의 예제를 지정할 수 있습니다. 예제에는 <code> 태그가 흔히 사용됩니다.

문서 텍스트 다시 사용

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

기본 클래스, 인터페이스 및 유사한 메서드에서 XML 주석을 상속합니다. inheritdoc를 사용하면 중복 XML 주석을 복사하여 붙여넣을 필요가 없으며 XML 주석이 자동으로 동기화됩니다. <inheritdoc> 태그를 형식에 추가하면 모든 멤버도 주석을 상속합니다.

• cref: 문서를 상속할 멤버를 지정합니다. 현재 멤버에서 이미 정의된 태그는 상속된 태그로 재정의되지 않습니다.
• path: 노드가 표시되도록 설정할 XPath 식 쿼리입니다. 이 특성을 사용하여 상속된 문서에서 포함하거나 제외할 태그를 필터링할 수 있습니다.

기본 클래스 또는 인터페이스에 XML 주석을 추가하고 inheritdoc가 주석을 구현 클래스에 복사하도록 합니다. 동기 메서드에 XML 주석을 추가하고 inheritdoc가 동일한 메서드의 비동기 버전에 주석을 복사하도록 합니다. 특정 멤버에서 주석을 복사하려면 cref 특성을 사용하여 멤버를 지정합니다.

<include>

<include file='filename' path='tagpath[@name="id"]' />

• filename: 문서가 포함된 XML 파일의 이름입니다. 파일 이름은 소스 코드 파일에 상대 경로로 한정될 수 있습니다. filename을 작은따옴표(‘ ’)로 묶습니다.
• tagpath: filename의 태그 경로로, name 태그에 연결됩니다. 경로를 작은따옴표(‘ ’)로 묶습니다.
• name: 주석 앞에 오는 태그의 이름 지정자입니다. name에는 id가 있습니다.
• id: 주석 앞에 오는 태그의 ID입니다. ID를 따옴표(")로 묶습니다.

<include> 태그를 사용하면 소스 코드의 형식과 멤버를 설명하는 다른 파일의 주석을 참조할 수 있습니다. 외부 파일을 포함하는 것은 소스 코드 파일에 직접 문서 주석을 두는 것에 대한 대안입니다. 별도 파일에 문서를 배치하면 소스 코드와 별도로 문서에 소스 제어를 적용할 수 있습니다. 한 사람은 소스 코드 파일을 체크 아웃하고 다른 사람은 문서 파일을 체크 아웃할 수 있습니다. <include> 태그는 XML XPath 구문을 사용합니다. <include> 사용을 사용자 지정하는 방법은 XPath 설명서를 참조하세요.

예를 들어 다음 소스 코드는 <include> 태그를 사용하여 설명을 포함합니다. 파일 경로는 원본에 상대적입니다.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

포함 파일의 XML 원본은 다음 샘플에 나와 있습니다. C# 컴파일러에서 생성한 XML 파일과 동일하게 구조화됩니다. XPath 식이 식별할 수 있는 한 XML 파일에는 여러 메서드 또는 형식에 대한 텍스트가 포함될 수 있습니다.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

이 메서드의 XML 출력은 다음 예제에 나와 있습니다.

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

팁

.NET 런타임 팀은 설명서에서 <include> 태그를 광범위하게 사용합니다. dotnet/runtime 리포지토리를 검색하여 많은 예제를 볼 수 있습니다.

링크 및 참조 생성

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>

• cref="member": 현재 컴파일 환경에서 호출할 수 있는 멤버 또는 필드에 대한 참조입니다. 컴파일러는 지정된 코드 요소가 있으며 member를 출력 XML의 요소 이름에 전달하는지 확인합니다. 멤버를 따옴표(")로 묶습니다. 별도의 닫는 태그를 사용하여 “cref”에 대해 다른 링크 텍스트를 제공할 수 있습니다.
• href="link": 지정된 URL의 클릭 가능한 링크입니다. 예를 들어 <see href="https://github.com">GitHub</see>는 https://github.com으로 연결되는 GitHub 텍스트가 포함된 클릭 가능한 링크를 생성합니다.
• langword="keyword": true 또는 다른 유효한 키워드와 같은 언어 키워드입니다.

<see> 태그를 사용하면 텍스트 내부에서 링크를 지정할 수 있습니다. <seealso>는 텍스트가 참고 항목 섹션에 배치되어야 함을 나타내는 데 사용합니다. 코드 요소의 문서 페이지에 대한 내부 하이퍼링크를 만들려면 cref 특성을 사용합니다. cref="IDictionary{T, U}"와 같은 제네릭 형식 또는 메서드에 대한 참조를 지정하려면 형식 매개 변수를 포함합니다. 또한 href는 하이퍼링크로 작동하는 유효한 특성입니다.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>

• cref="member": 현재 컴파일 환경에서 호출할 수 있는 멤버 또는 필드에 대한 참조입니다. 컴파일러는 지정된 코드 요소가 있으며 member를 출력 XML의 요소 이름에 전달하는지 확인합니다. member는 따옴표(") 안에 표시되어야 합니다.
• href="link": 지정된 URL의 클릭 가능한 링크입니다. 예를 들어 <seealso href="https://github.com">GitHub</seealso>는 https://github.com으로 연결되는 GitHub 텍스트가 포함된 클릭 가능한 링크를 생성합니다.

<seealso> 태그를 사용하면 참고 항목 섹션에 표시할 텍스트를 지정할 수 있습니다. 텍스트 내에서 링크를 지정하려면 <see>를 사용합니다. summary 태그 내에 seealso 태그를 중첩할 수 없습니다.

cref 특성

XML 문서 태그의 cref 특성은 "코드 참조"를 의미합니다. 태그의 내부 텍스트를 형식, 메서드, 속성 등의 코드 요소로 지정합니다. DocFX 및 Sandcastle 등의 문서화 도구는 cref 특성을 사용하여 형식 또는 멤버가 문서화된 페이지에 대한 하이퍼링크를 자동으로 생성합니다.

href 특성

href 특성은 웹 페이지에 대한 참조를 의미합니다. API 또는 라이브러리에 대한 온라인 문서를 직접 참조하는 데 사용할 수 있습니다.

제네릭 형식 및 메서드

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>

• TResult: 형식 매개 변수의 이름입니다. 이름을 따옴표(")로 묶습니다.

<typeparam> 태그는 제네릭 형식 또는 메서드 선언의 주석에서 형식 매개 변수를 설명하는 데 사용해야 합니다. 제네릭 형식 또는 메서드의 각 형식 매개 변수에 대한 태그를 추가합니다. <typeparam> 태그의 텍스트가 IntelliSense에 표시됩니다.

<typeparamref>

<typeparamref name="TKey"/>

• TKey: 형식 매개 변수의 이름입니다. 이름을 따옴표(")로 묶습니다.

이 태그를 사용하면 문서 파일의 소비자가 기울임꼴 등 다른 고유한 방식으로 단어의 서식을 지정할 수 있습니다.

사용자 정의 태그

이 문서에서 설명한 모든 태그는 C# 컴파일러에서 인식되는 태그를 나타냅니다. 그러나 사용자가 자유롭게 태그를 정의할 수 있습니다. Sandcastle과 같은 도구는 <event>, <note> 같은 추가 태그를 지원하고, 네임스페이스 문서화도 지원합니다. 사용자 지정 또는 사내 문서 생성 도구는 표준 태그와 함께 사용할 수도 있고 HTML에서 PDF까지 다양한 출력 형식을 지원할 수 있습니다.