부록 D 문서 주석

이 별관은 유익합니다.

D.1 일반

C#은 프로그래머가 XML 텍스트가 포함된 주석 구문을 사용하여 코드를 문서화할 수 있는 메커니즘을 제공합니다. 소스 코드 파일에서 특정 형식의 주석을 사용하여 해당 주석과 그 앞에 있는 소스 코드 요소에서 XML을 생성하도록 도구를 지시할 수 있습니다. 이러한 구문을 사용하는 주석을 문서 주석이라고 합니다. 사용자 정의 형식(예: 클래스, 대리자 또는 인터페이스) 또는 멤버(예: 필드, 이벤트, 속성 또는 메서드) 바로 앞에 와야 합니다. XML 생성 도구를 문서 생성기라고 합니다. (이 생성기는 C# 컴파일러 자체일 수 있지만 반드시 그럴 필요는 없습니다.) 문서 생성기에서 생성된 출력을 문서 파일이라고 합니다. 문서 파일은 문서 뷰어에 대한 입력으로 사용됩니다. 유형 정보 및 관련 문서를 시각적으로 표시하기 위한 도구입니다.

준수하는 C# 컴파일러는 문서 주석의 구문을 확인할 필요가 없습니다. 그런 말은 그저 평범한 말일 뿐이다. 그러나 준수하는 컴파일러는 이러한 검사를 수행할 수 있습니다.

이 사양은 문서 주석에 사용할 표준 태그 집합을 제안하지만 이러한 태그의 사용은 필요하지 않으며 올바른 형식의 XML 규칙을 따르는 한 원하는 경우 다른 태그를 사용할 수 있습니다. CLI를 대상으로 하는 C# 구현의 경우 설명서 생성기 및 설명서 파일의 형식에 대한 정보도 제공합니다. 문서 뷰어에 대한 정보는 제공되지 않습니다.

D.2 소개

특정 형식을 가진 주석은 해당 주석과 그 앞에 오는 소스 코드 요소에서 XML을 생성하도록 도구를 지시하는 데 사용할 수 있습니다. 이러한 주석은 세 개의 슬래시()로 시작하는 Single_Line_Comment(§6.3.3) 또는 슬래시와/// 두 개의 별표()/**로 시작하는 Delimited_Comment(§6.3.3)입니다. 사용자 정의 형식 또는 주석을 추가하는 멤버 바로 앞에 와야 합니다. 특성 섹션(§22.3)은 선언의 일부로 간주되므로 문서 주석은 형식 또는 멤버에 적용되는 특성보다 우선해야 합니다.

설명을 위해 문서 주석의 형식은 아래에 Single_Line_Doc_Comment 및 Delimited_Doc_Comment의 두 가지 문법 규칙으로 표시됩니다. 그러나 이러한 규칙은 C# 문법의 일부가 아니라 각각 특정 형식의 Single_Line_Comment 및 Delimited_Comment 렉서 규칙을 나타냅니다.

통사론:

Single_Line_Doc_Comment
    : '///' Input_Character*
    ;
   
Delimited_Doc_Comment
    : '/**' Delimited_Comment_Section* ASTERISK+ '/'
    ;

Single_Line_Doc_Comment에서 현재 Single_Line_Doc_Comment에 인접한 각 Single_Line_Doc_Comments의 문자 뒤에 ///공백 문자가 있으면 해당 공백 문자는 XML 출력에 포함되지 않습니다.

Delimited_Doc_Comment에서 두 번째 줄의 첫 번째 비공백 문자가 ASTERISK이고 동일한 패턴의 선택적 공백 문자와 ASTERISK 문자가 Delimited_Doc_Comment 내의 각 행의 시작 부분에서 반복되는 경우 반복되는 패턴의 문자는 XML 출력에 포함되지 않습니다. 패턴은 ASTERISK 문자 앞뿐만 아니라 뒤에도 공백 문자를 포함할 수 있습니다.

예제:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
    /// <summary>
    /// Method <c>Draw</c> renders the point.
    /// </summary>
    void Draw() {...}
}

문서 주석 내의 텍스트는 XML()http://www.w3.org/TR/REC-xml의 규칙에 따라 올바른 형식이어야 합니다. XML이 잘못 구성된 경우 경고가 생성되고 문서 파일에 오류가 발생했음을 나타내는 주석이 포함됩니다.

개발자는 자신의 태그 집합을 자유롭게 만들 수 있지만 권장 집합은 §D.3에 정의되어 있습니다. 권장 태그 중 일부는 특별한 의미가 있습니다.

• 태그 <param> 는 매개 변수를 설명하는 데 사용됩니다. 이러한 태그를 사용하는 경우 설명서 생성기는 지정된 매개 변수가 존재하고 모든 매개 변수가 설명서 주석에 설명되어 있는지 확인해야 합니다. 이러한 확인에 실패하면 문서 생성기에서 경고를 발생시킵니다.

• cref 특성을 태그에 연결하여 코드 요소에 대한 참조를 제공할 수 있습니다. 설명서 생성기는 이 코드 요소가 있는지 확인해야 합니다. 확인에 실패하면 문서 생성기에서 경고를 발생시킵니다. 속성에 설명된 cref 이름을 찾을 때 문서 생성기는 소스 코드 내에 나타나는 using 문에 따라 네임스페이스 가시성을 존중해야 합니다. 제네릭 코드 요소의 경우 일반 제네릭 구문(예: "List<T>")은 잘못된 XML을 생성하므로 사용할 수 없습니다. 괄호 대신 중괄호를 사용할 수 있습니다(예: "List{T}") 또는 XML 이스케이프 구문(예: "List<T>")을 사용할 수 있습니다.

• 태그는 <summary> 문서 뷰어에서 유형 또는 멤버에 대한 추가 정보를 표시하는 데 사용됩니다.

• 태그에는 <include> 외부 XML 파일의 정보가 포함됩니다.

설명서 파일은 형식 및 멤버에 대한 전체 정보를 제공하지 않습니다(예: 형식 정보가 포함되어 있지 않음). 형식 또는 멤버에 대한 이러한 정보를 가져오려면 형식 또는 멤버에 대한 리플렉션과 함께 설명서 파일을 사용해야 합니다.

부분 형식(Partial Type) 또는 부분 메서드(Partial Method)는 여러 부분으로 선언할 수 있으며, 각 부분은 하나 이상의 컴파일 단위에 있을 수 있으며 각 부분에는 하나 이상의 설명서 주석이 있을 수 있습니다. 부분 메서드에는 일반적으로 "partial 선언 정의"와 "partial 선언 구현"이 있습니다.

부분 타입의 경우, 각 파트에서 해당 타입에 직접 적용되는 문서 주석이 있는 경우 모두 지정되지 않은 순서로 문서 파일에 기록됩니다.

부분 메서드의 경우:

• 정의하는 partial 선언에 해당하는 구현 partial 선언이 없는 경우, 해당 partial 선언을 정의하는 문서의 주석은 무시됩니다(해당 선언이 제거되므로).
• 그렇지 않으면 구현하는 partial 선언에 문서 주석이 있는 경우 해당 주석이 문서 파일에 기록되고 defining partial 선언의 모든 문서 주석은 무시됩니다.
• 그렇지 않으면 defining partial 선언의 모든 문서 주석이 문서 파일에 기록됩니다.

D.3 추천 태그

D.3.1 일반

문서 생성기는 XML의 규칙에 따라 유효한 모든 태그를 수락하고 처리해야 합니다. 다음 태그는 사용자 설명서에서 일반적으로 사용되는 기능을 제공합니다. (물론 다른 태그도 가능합니다.)

D.3.2 <씨>

이 태그는 설명 내의 텍스트 조각이 코드 블록에 사용되는 것과 같은 특수 글꼴로 설정되어야 함을 나타내는 메커니즘을 제공합니다. 실제 코드 줄의 경우 (§D.3.3)을 사용합니다 <code> .

통사론:

<c> 문자 메시지</c>

예제:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
}

D.3.3 <코드>

이 태그는 하나 이상의 소스 코드 또는 프로그램 출력을 특수 글꼴로 설정하는 데 사용됩니다. 내러티브의 작은 코드 조각의 경우 (§D.3.2)를 사용합니다 <c> .

통사론:

<code> 소스 코드 또는 프로그램 출력</code>

예제:

public class Point
{
    /// <summary>
    /// This method changes the point's ___location by the given x- and y-offsets.
    /// <example>
    /// For example:
    /// <code>
    /// Point p = new Point(3,5);
    /// p.Translate(-1,3);
    /// </code>
    /// results in <c>p</c>'s having the value (2,8).
    /// </example>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.4 <예시>

이 태그를 사용하면 주석 내의 예제 코드를 사용하여 메서드 또는 다른 라이브러리 멤버를 사용하는 방법을 지정할 수 있습니다. 일반적으로 여기에는 태그 <code> (§D.3.3)의 사용도 포함됩니다.

통사론:

<example> 묘사</example>

예제:

예를 들어 (§D.3.3)을 참조하십시오 <code> .

D.3.5 <예외>

이 태그는 메서드에서 throw할 수 있는 예외를 문서화하는 방법을 제공합니다.

통사론:

<exception cref=" 구성원">묘사</exception>

어디

• cref=" 구성원" 은 멤버의 이름입니다. 문서 생성기는 지정된 멤버가 있는지 확인하고 member 를 문서 파일의 표준 요소 이름으로 변환합니다.
• description 은 예외가 throw되는 상황에 대한 설명입니다.

예제:

class PrimaryFileFormatCorruptException : System.Exception { ... }
class PrimaryFileLockedOpenException : System.Exception { ... }

public class DataBaseOperations
{
    /// <exception cref="PrimaryFileFormatCorruptException">
    /// Thrown when the primary file is corrupted.
    /// </exception>
    /// <exception cref="PrimaryFileLockedOpenException">
    /// Thrown when the primary file is already open.
    /// </exception>
    public static void ReadRecord(int flag)
    {
        if (flag == 1)
        {
            throw new PrimaryFileFormatCorruptException();
        }
        else if (flag == 2)
        {
            throw new PrimaryFileLockedOpenException();
        }
        ...
    }
}

D.3.6 <포함>

이 태그를 사용하면 소스 코드 파일 외부에 있는 XML 문서의 정보를 포함할 수 있습니다. 외부 파일은 올바른 형식의 XML 문서여야 하며, 해당 문서에 XPath 표현식이 적용되어 해당 문서에서 포함할 XML을 지정합니다. 그런 다음 태그는 <include> 외부 문서에서 선택한 XML로 바뀝니다.

구문:

<include file=" 파일" path="XPath" />

어디

• file=" 파일" 은 외부 XML 파일의 파일 이름입니다. 파일 이름은 include 태그를 포함하는 파일을 기준으로 해석됩니다.
• path=" XPath" 는 외부 XML 파일에서 일부 XML을 선택하는 XPath 표현식입니다.

예제:

소스 코드에 다음과 같은 선언이 포함된 경우:

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { ... }

외부 파일 "docs.xml"의 내용은 다음과 같습니다.

<?xml version="1.0"?>
<extradoc>
    <class name="IntList">
        <summary>
            Contains a list of integers.
        </summary>
    </class>
    <class name="StringList">
        <summary>
            Contains a list of strings.
        </summary>
    </class>
</extradoc>

그런 다음 소스 코드에 포함 된 것처럼 동일한 문서가 출력됩니다.

/// <summary>
/// Contains a list of integers.
/// </summary>
public class IntList { ... }

D.3.7 <목록>

이 태그는 항목의 목록 또는 테이블을 만드는 데 사용됩니다. 여기에는 테이블 또는 정의 목록의 표제 행을 정의하는 블록이 포함될 <listheader> 수 있습니다. (테이블을 정의할 때 제목의 term 에 대한 항목만 제공하면 됩니다.)

목록의 각 항목은 블록으로 <item> 지정됩니다. 정의 목록을 만들 때 용어 와 설명을 모두 지정해야 합니다. 그러나 테이블, 글머리 기호 목록 또는 번호 매기기 목록의 경우 설명 만 지정하면 됩니다.

통사론:

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
    ...
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

어디

• term 은 정의해야 할 용어이며, 그 정의는 description에 있습니다.
• description 은 글머리 기호 또는 번호 매기기 목록의 항목이거나 용어의 정의입니다.

예제:

public class MyClass
{
    /// <summary>Here is an example of a bulleted list:
    /// <list type="bullet">
    /// <item>
    /// <description>Item 1.</description>
    /// </item>
    /// <item>
    /// <description>Item 2.</description>
    /// </item>
    /// </list>
    /// </summary>
    public static void Main()
    {
        ...
    }
}

D.3.8 <단락>

이 태그는 (§D.3.16) 또는 <returns> (§D.3.13)과 같은 <summary> 다른 태그 내에서 사용하기 위한 것이며 텍스트에 구조를 추가할 수 있습니다.

통사론:

<para> 콘텐츠</para>

어디

• content 는 단락의 텍스트입니다.

예제:

public class Point
{
    /// <summary>This is the entry point of the Point class testing program.
    /// <para>
    /// This program tests each method and operator, and
    /// is intended to be run after any non-trivial maintenance has
    /// been performed on the Point class.
    /// </para>
    /// </summary>
    public static void Main() 
    {
        ...
    }
}

D.3.9 <매개 변수>

이 태그는 메서드, 생성자 또는 인덱서에 대한 매개 변수를 설명하는 데 사용됩니다.

통사론:

<param name=" 이름">묘사</param>

어디

• name 은 매개 변수의 이름입니다.
• description 은 매개 변수에 대한 설명입니다.

예제:

public class Point
{
    /// <summary>
    /// This method changes the point's ___location to
    /// the given coordinates.
    /// </summary>
    /// <param name="xPosition">the new x-coordinate.</param>
    /// <param name="yPosition">the new y-coordinate.</param>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
}

D.3.10 <매개 변수 참조>

이 태그는 단어가 매개변수임을 나타내는 데 사용됩니다. 문서 파일을 처리하여 이 매개 변수의 형식을 고유한 방식으로 지정할 수 있습니다.

통사론:

<paramref name=" 이름"/>

어디

• name 은 매개 변수의 이름입니다.

예제:

public class Point
{
    /// <summary>This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    /// <param name="xPosition">the new Point's x-coordinate.</param>
    /// <param name="yPosition">the new Point's y-coordinate.</param>
    public Point(int xPosition, int yPosition)
    {
        ...
    }
}

D.3.11 <권한>

이 태그를 사용하면 구성원의 보안 접근성을 문서화할 수 있습니다.

통사론:

<permission cref=" 구성원">묘사</permission>

어디

• member 는 멤버의 이름입니다. 문서 생성기는 주어진 코드 요소가 존재하는지 확인하고 member 를 문서 파일의 표준 요소 이름으로 변환합니다.
• description 은 멤버에 대한 액세스에 대한 설명입니다.

예제:

public class MyClass
{
    /// <permission cref="System.Security.PermissionSet">
    /// Everyone can access this method.
    /// </permission>
    public static void Test()
    {
        ...
    }
}

D.3.12 <비고>

이 태그는 유형에 대한 추가 정보를 지정하는 데 사용됩니다. (§D.3.16)을 사용하여 <summary> 형식 자체와 형식의 멤버를 설명합니다.

통사론:

<remarks> 묘사</remarks>

어디

• description 은 발언의 텍스트입니다.

예제:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
/// <remarks>
/// Uses polar coordinates
/// </remarks>
public class Point
{
    ...
}

D.3.13 <반환>

이 태그는 메서드의 반환 값을 설명하는 데 사용됩니다.

통사론:

<returns> 묘사</returns>

어디

• description 은 반환 값에 대한 설명입니다.

예제:

public class Point
{
    /// <summary>
    /// Report a point's ___location as a string.
    /// </summary>
    /// <returns>
    /// A string representing a point's ___location, in the form (x,y),
    /// without any leading, trailing, or embedded whitespace.
    /// </returns>
    public override string ToString() => $"({X},{Y})";
    public int X { get; set; }
    public int Y { get; set; }
}

D.3.14 <참조>

이 태그를 사용하면 텍스트 내에 링크를 지정할 수 있습니다. (§D.3.15)를 사용하여 <seealso>See Also 하위 절에 표시할 텍스트를 나타냅니다.

통사론:

<see cref=" 구성원" href="url입니다." langword="키워드" />

어디

• member 는 멤버의 이름입니다. 문서 생성기는 지정된 코드 요소가 있는지 확인하고 생성된 문서 파일의 요소 이름으로 멤버 를 변경합니다.
• url 은 외부 소스에 대한 참조입니다.
• langword 는 어떻게든 강조해야 할 단어입니다.

예제:

public class Point
{
    /// <summary>
    /// This method changes the point's ___location to
    /// the given coordinates. <see cref="Translate"/>
    /// </summary>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
    /// <summary>This method changes the point's ___location by
    /// the given x- and y-offsets. <see cref="Move"/>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.15 <참조또한>

이 태그를 사용하면 See Also 하위 절에 대한 항목을 생성할 수 있습니다 . (§D.3.14)를 사용하여 <see> 텍스트 내에서 링크를 지정합니다.

통사론:

<seealso cref=" 구성원" href="url입니다." />

어디

• member 는 멤버의 이름입니다. 문서 생성기는 지정된 코드 요소가 있는지 확인하고 생성된 문서 파일의 요소 이름으로 멤버 를 변경합니다.
• url 은 외부 소스에 대한 참조입니다.

예제:

public class Point
{
    /// <summary>
    /// This method determines whether two Points have the same ___location.
    /// </summary>
    /// <seealso cref="operator=="/>
    /// <seealso cref="operator!="/>
    public override bool Equals(object o)
    {
        ...
    }
}

D.3.16 <요약>

이 태그는 형식 또는 형식의 멤버를 설명하는 데 사용할 수 있습니다. (§D.3.12)를 사용하여 <remarks> 형식 또는 멤버에 대한 추가 정보를 지정합니다.

통사론:

<summary> 묘사</summary>

어디

• description 은 유형 또는 멤버에 대한 요약입니다.

예제:

public class Point
{

    /// <summary>
    /// This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    public Point(int xPosition, int yPosition) 
    {
        ...
    }

    /// <summary>This constructor initializes the new Point to (0,0).</summary>
    public Point() : this(0, 0)
    {
    }
}

D.3.17 <타입 파라미터>

이 태그는 제네릭 형식 또는 메서드에 대한 형식 매개 변수를 설명하는 데 사용됩니다.

통사론:

<typeparam name=" 이름">묘사</typeparam>

어디

• name 은 type 매개 변수의 이름입니다.
• description 은 type 매개 변수에 대한 설명입니다.

예제:

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T>
{
   ...
}

D.3.18 <타입파라메프르>

이 태그는 단어가 형식 매개 변수임을 나타내는 데 사용됩니다. 문서 파일을 처리하여 이 유형 매개변수의 형식을 고유한 방식으로 지정할 수 있습니다.

통사론:

<typeparamref name=" 이름"/>

어디

• name 은 type 매개 변수의 이름입니다.

예제:

public class MyClass
{
    /// <summary>
    /// This method fetches data and returns a list of
    /// <typeparamref name="T"/>.
    /// </summary>
    /// <param name="query">query to execute</param>
    public List<T> FetchData<T>(string query)
    {
        ...
    }
}

D.3.19 <값>

이 태그를 사용하면 속성을 설명할 수 있습니다.

통사론:

<value> 부동산 설명</value>

어디

• 속성 설명은 속성에 대한 설명입니다.

예제:

public class Point
{
    /// <value>Property <c>X</c> represents the point's x-coordinate.</value>
    public int X { get; set; }
}

D.4 문서 파일 처리

D.4.1 일반

다음 정보는 CLI를 대상으로 하는 C# 구현을 위한 것입니다.

설명서 생성기는 문서 주석으로 태그가 지정된 소스 코드의 각 요소에 대한 ID 문자열을 생성합니다. 이 ID 문자열은 원본 요소를 고유하게 식별합니다. 문서 뷰어는 ID 문자열을 사용하여 문서가 적용되는 해당 항목을 식별할 수 있습니다.

문서 파일은 소스 코드의 계층적 표현이 아닙니다. 오히려 각 요소에 대해 생성된 ID 문자열이 있는 플랫 목록입니다.

D.4.2 ID 문자열 형식

문서 생성기는 ID 문자열을 생성할 때 다음 규칙을 준수합니다.

• 문자열에 공백이 삽입되지 않습니다.

• 문자열의 첫 번째 부분은 단일 문자와 콜론을 통해 문서화되는 멤버의 종류를 식별합니다. 다음과 같은 종류의 멤버가 정의됩니다.

  문자	설명
  E	이벤트
  F	분야
  M	메서드(생성자, 종료자 및 연산자 포함)
  N	네임스페이스
  P	속성(인덱서 포함)
  T	형식(예: class, delegate, enum, interface 및 struct)
  !	오류 문자열; 문자열의 나머지 부분은 오류에 대한 정보를 제공합니다. 예를 들어 설명서 생성기는 확인할 수 없는 링크에 대한 오류 정보를 생성합니다.

• 문자열의 두 번째 부분은 네임스페이스의 루트에서 시작하는 요소의 정규화된 이름입니다. 요소의 이름, 바깥쪽 형식 및 네임스페이스는 마침표로 구분됩니다. 항목 이름 자체에 마침표가 있으면 # (U+0023) 문자로 바뀝니다. (이름에 이 문자가 있는 요소는 없다고 가정합니다.) 멤버가 제네릭 인터페이스의 멤버를 명시적으로 구현하는 경우 정규화된 이름의 형식 인수는 이를 둘러싼 "<" 및 ">"를 "{" 및 "}" 문자로 바꿔 인코딩됩니다.

• 인수가 있는 메서드와 속성의 경우 인수 목록이 괄호로 묶여 있습니다. 인수가 없는 경우 괄호가 생략됩니다. 인수는 쉼표로 구분됩니다. 각 인수의 인코딩은 다음과 같이 CLI 서명과 동일합니다.

  • 인수는 다음과 같이 수정된 정규화된 이름을 기반으로 하는 문서 이름으로 표시됩니다.
    • 제네릭 형식을 나타내는 인수에는 "'" 문자가 추가되고 그 뒤에 형식 매개 변수의 수가 있습니다
    • 또는 outref 한정자가 있는 in인수는 뒤에 형식 이름이 있습니다@. value 또는 via params 로 전달된 인수에는 특별한 표기법이 없습니다.
    • 배열인 인수는 [하한:크기, ... , 하한선:크기] 여기서 쉼표의 수는 1보다 순위가 적고, 각 차원의 하한과 크기(알려진 경우)는 10진수로 표시됩니다. 하한 또는 크기를 지정하지 않으면 생략됩니다. 특정 차원에 대한 하한과 크기를 생략하면 ":"도 생략됩니다. 들쭉날쭉한 배열은 레벨당 하나의 "[]"로 표시됩니다. 1차원 배열은 하한이 0(기본값)일 때 하한을 생략합니다(§17.1).
    • 이외의 void 포인터 형식이 있는 인수는 다음 형식 이름을 사용하여 * 표시됩니다. 포인터는 void 의 형식 이름을 System.Void사용하여 표시됩니다.
    • 형식에 정의된 제네릭 형식 매개 변수를 참조하는 인수는 "`" 문자 뒤에 type 매개 변수의 0부터 시작하는 인덱스를 사용하여 인코딩됩니다.
    • 메서드에 정의된 제네릭 형식 매개 변수를 사용하는 인수는 형식에 사용되는 "`" 대신 이중 백틱 "``"를 사용합니다.
    • 생성된 제네릭 형식을 참조하는 인수는 제네릭 형식, "{", 쉼표로 구분된 형식 인수 목록, "}" 순을 사용하여 인코딩됩니다.

D.4.3 ID 문자열 예제

다음 각 예제에서는 문서 주석을 포함할 수 있는 각 소스 요소에서 생성된 ID 문자열과 함께 C# 코드 조각을 보여 줍니다.

형식은 정규화된 이름을 사용하여 표시되며 일반 정보로 보강됩니다.

enum Color { Red, Blue, Green }

namespace Acme
{
    interface IProcess { ... }

    struct ValueType { ... }

    class Widget : IProcess
    {
        public class NestedClass { ... }
        public interface IMenuItem { ... }
        public delegate void Del(int i);
        public enum Direction { North, South, East, West }
    }

    class MyList<T>
    {
        class Helper<U,V> { ... }
    }
}

아이디:

"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"
"T:Acme.MyList`1"
"T:Acme.MyList`1.Helper`2"

필드는 정규화된 이름으로 표시됩니다.

namespace Acme
{
    struct ValueType
    {
        private int total;
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            private int value;
        }

        private string message;
        private static Color defaultColor;
        private const double PI = 3.14159;
        protected readonly double monthlyAverage;
        private long[] array1;
        private Widget[,] array2;
        private unsafe int *pCount;
        private unsafe float **ppValues;
    }
}

아이디:

"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"
"F:Acme.Widget.pCount"
"F:Acme.Widget.ppValues"

생성자

namespace Acme
{
    class Widget : IProcess
    {
        static Widget() { ... }
        public Widget() { ... }
        public Widget(string s) { ... }
    }
}

아이디:

"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"

파이널라이저

namespace Acme
{
    class Widget : IProcess
    {
        ~Widget() { ... }
    }
}

아이디:

"M:Acme.Widget.Finalize"

메서드

namespace Acme
{
    struct ValueType
    {
        public void M(int i) { ... }
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            public void M(int i) { ... }
        }

        public static void M0() { ... }
        public void M1(char c, out float f, ref ValueType v, in int i) { ... }
        public void M2(short[] x1, int[,] x2, long[][] x3) { ... }
        public void M3(long[][] x3, Widget[][,,] x4) { ... }
        public unsafe void M4(char *pc, Color **pf) { ... }
        public unsafe void M5(void *pv, double *[][,] pd) { ... }
        public void M6(int i, params object[] args) { ... }
    }

    class MyList<T>
    {
        public void Test(T t) { ... }
    }

    class UseList
    {
        public void Process(MyList<int> list) { ... }
        public MyList<T> GetValues<T>(T value) { ... } 
    }
}

아이디:

"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@,System.Int32@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Char*,Color**)"
"M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
"M:Acme.Widget.M6(System.Int32,System.Object[])"
"M:Acme.MyList`1.Test(`0)"
"M:Acme.UseList.Process(Acme.MyList{System.Int32})"
"M:Acme.UseList.GetValues``1(``0)"

속성 및 인덱서

namespace Acme
{
    class Widget : IProcess
    {
        public int Width { get { ... } set { ... } }
        public int this[int i] { get { ... } set { ... } }
        public int this[string s, int i] { get { ... } set { ... } }
    }
}

아이디:

"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"

이벤트

namespace Acme
{
    class Widget : IProcess
    {
        public event Del AnEvent;
    }
}

아이디:

"E:Acme.Widget.AnEvent"

단항 연산자

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x) { ... }
    }
}

아이디:

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"

사용되는 단항 연산자 함수 이름의 전체 집합은 , op_UnaryPlusop_UnaryNegation, op_LogicalNot, op_Decrementop_Trueop_OnesComplementop_Increment및 op_False입니다.

이항 연산자

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x1, Widget x2) { ... }
    }
}

아이디:

"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"

사용되는 이항 연산자 함수 이름의 전체 집합은 , op_Additionop_Subtraction, op_Multiply, op_Division, op_BitwiseAndop_LeftShiftop_ExclusiveOrop_RightShiftop_Equalityop_BitwiseOrop_Modulusop_LessThanop_LessThanOrEqualop_Inequalityop_GreaterThan및 op_GreaterThanOrEqual입니다.

변환 연산자 에는 후행 "~" 뒤에 반환 형식이 있습니다. 변환 연산자의 소스 또는 대상이 제네릭 형식인 경우 "<" 및 "">" 문자는 각각 "{" 및 "}" 문자로 바뀝니다.

namespace Acme
{
    class Widget : IProcess
    {
        public static explicit operator int(Widget x) { ... }
        public static implicit operator long(Widget x) { ... }
    }
}

아이디:

"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"

D.5 예시

D.5.1 C# 소스 코드

다음 예제에서는 Point 클래스의 소스 코드를 보여 줍니다.

namespace Graphics
{
    /// <summary>
    /// Class <c>Point</c> models a point in a two-dimensional plane.
    /// </summary>
    public class Point
    {
        /// <value>
        /// Property <c>X</c> represents the point's x-coordinate.
        /// </value>
        public int X { get; set; }
        
        /// <value>
        /// Property <c>Y</c> represents the point's y-coordinate.
        /// </value>
        public int Y { get; set; }
        
        /// <summary>
        /// This constructor initializes the new Point to (0,0).
        /// </summary>
        public Point() : this(0, 0) {}
        
        /// <summary>
        /// This constructor initializes the new Point to
        /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
        /// </summary>
        /// <param name="xPosition">The new Point's x-coordinate.</param>
        /// <param name="yPosition">The new Point's y-coordinate.</param>
        public Point(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's ___location to
        /// the given coordinates. <see cref="Translate"/>
        /// </summary>
        /// <param name="xPosition">The new x-coordinate.</param>
        /// <param name="yPosition">The new y-coordinate.</param>
        public void Move(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's ___location by
        /// the given x- and y-offsets.
        /// <example>For example:
        /// <code>
        /// Point p = new Point(3, 5);
        /// p.Translate(-1, 3);
        /// </code>
        /// results in <c>p</c>'s having the value (2, 8).
        /// <see cref="Move"/>
        /// </example>
        /// </summary>
        /// <param name="dx">The relative x-offset.</param>
        /// <param name="dy">The relative y-offset.</param>
        public void Translate(int dx, int dy)
        {
            X += dx;
            Y += dy;
        }
        
        /// <summary>
        /// This method determines whether two Points have the same ___location.
        /// </summary>
        /// <param name="o">
        /// The object to be compared to the current object.
        /// </param>
        /// <returns>
        /// True if the Points have the same ___location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="operator=="/>
        /// <seealso cref="operator!="/>
        public override bool Equals(object o)
        {
            if (o == null)
            {
                return false;
            }
            if ((object)this == o) 
            {
                return true;
            }
            if (GetType() == o.GetType()) 
            {
                Point p = (Point)o;
                return (X == p.X) && (Y == p.Y);
            }
            return false;
        }

        /// <summary>
        /// This method returns a Point's hashcode.
        /// </summary>
        /// <returns>
        /// The int hashcode.
        /// </returns>
        public override int GetHashCode()
        {
            return X + (Y >> 4);    // a crude version
        }
        
        /// <summary>Report a point's ___location as a string.</summary>
        /// <returns>
        /// A string representing a point's ___location, in the form (x,y),
        /// without any leading, training, or embedded whitespace.
        /// </returns>
        public override string ToString() => $"({X},{Y})";
        
        /// <summary>
        /// This operator determines whether two Points have the same ___location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points have the same ___location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator!="/>
        public static bool operator==(Point p1, Point p2)
        {
            if ((object)p1 == null || (object)p2 == null)
            {
                return false;
            }
            if (p1.GetType() == p2.GetType())
            {
                return (p1.X == p2.X) && (p1.Y == p2.Y);
            }
            return false;
        }
        
        /// <summary>
        /// This operator determines whether two Points have the same ___location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points do not have the same ___location and the
        /// exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator=="/>
        public static bool operator!=(Point p1, Point p2) => !(p1 == p2);
    }
}

D.5.2 결과 XML

다음은 위에 표시된 class Point의 소스 코드가 주어졌을 때 하나의 문서 생성기에서 생성된 출력입니다.

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>Point</name>
  </assembly>
  <members>
    <member name="T:Graphics.Point">
    <summary>Class <c>Point</c> models a point in a two-dimensional
    plane.
    </summary>
    </member>
    <member name="M:Graphics.Point.#ctor">
      <summary>This constructor initializes the new Point to (0, 0).</summary>
    </member>
    <member name="M:Graphics.Point.#ctor(System.Int32,System.Int32)">
      <summary>
        This constructor initializes the new Point to
        (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
      </summary>
      <param name="xPosition">The new Point's x-coordinate.</param>
      <param name="yPosition">The new Point's y-coordinate.</param>
    </member>
    <member name="M:Graphics.Point.Move(System.Int32,System.Int32)">
      <summary>
        This method changes the point's ___location to
        the given coordinates.
        <see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
      </summary>
      <param name="xPosition">The new x-coordinate.</param>
      <param name="yPosition">The new y-coordinate.</param>
      </member>
    <member name="M:Graphics.Point.Translate(System.Int32,System.Int32)">
      <summary>
        This method changes the point's ___location by
        the given x- and y-offsets.
        <example>For example:
        <code>
        Point p = new Point(3,5);
        p.Translate(-1,3);
        </code>
        results in <c>p</c>'s having the value (2,8).
        </example>
        <see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
      </summary>
      <param name="dx">The relative x-offset.</param>
      <param name="dy">The relative y-offset.</param>
    </member>
    <member name="M:Graphics.Point.Equals(System.Object)">
      <summary>
        This method determines whether two Points have the same ___location.
      </summary>
      <param name="o">
        The object to be compared to the current object.
      </param>
      <returns>
        True if the Points have the same ___location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso 
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)" />
      <seealso 
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
     <member name="M:Graphics.Point.ToString">
      <summary>
        Report a point's ___location as a string.
      </summary>
      <returns>
        A string representing a point's ___location, in the form (x,y),
        without any leading, training, or embedded whitespace.
      </returns>
     </member>
    <member name="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same ___location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points have the same ___location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
    <member
        name="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same ___location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points do not have the same ___location and the
        exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
      </member>
      <member name="M:Graphics.Point.Main">
        <summary>
          This is the entry point of the Point class testing program.
          <para>
            This program tests each method and operator, and
            is intended to be run after any non-trivial maintenance has
            been performed on the Point class.
          </para>
        </summary>
      </member>
      <member name="P:Graphics.Point.X">
        <value>
          Property <c>X</c> represents the point's x-coordinate.
        </value>
      </member>
      <member name="P:Graphics.Point.Y">
        <value>
          Property <c>Y</c> represents the point's y-coordinate.
        </value>
    </member>
  </members>
</doc>

정보 텍스트의 끝입니다.