부록 D 설명서 주석
이 부록은 유익합니다.
D.1 일반
C#은 프로그래머가 XML 텍스트가 포함된 주석 구문을 사용하여 코드를 문서화하는 메커니즘을 제공합니다. 소스 코드 파일에서 특정 폼이 있는 주석을 사용하여 해당 주석 및 소스 코드 요소에서 XML을 생성하도록 도구를 지시할 수 있습니다. 이러한 구문을 사용하는 주석을 설명서 주석이라고 합니다. 사용자 정의 형식(예: 클래스, 대리자 또는 인터페이스) 또는 멤버(예: 필드, 이벤트, 속성 또는 메서드) 바로 앞에 와야 합니다. XML 생성 도구를 설명서 생성기라고 합니다. (이 생성기는 C# 컴파일러 자체일 수 있지만 그럴 필요는 없습니다.) 설명서 생성기에서 생성된 출력을 설명서 파일이라고 합니다. 설명서 파일은 문서 뷰어에 대한 입력으로 사용됩니다. 형식 정보와 관련 설명서의 시각적 표시를 생성하기 위한 도구입니다.
준수 C# 컴파일러는 설명서 주석의 구문을 확인할 필요가 없습니다. 이러한 의견은 단순히 평범한 의견입니다. 그러나 준수 컴파일러는 이러한 검사를 수행할 수 있습니다.
이 사양은 설명서 주석에 사용할 표준 태그 집합을 제안하지만 이러한 태그를 사용할 필요는 없으며, 올바른 형식의 XML 규칙을 따르는 한 원하는 경우 다른 태그를 사용할 수 있습니다. CLI를 대상으로 하는 C# 구현의 경우 설명서 생성기 및 설명서 파일 형식에 대한 정보도 제공합니다. 설명서 뷰어에 대한 정보는 제공되지 않습니다.
D.2 소개
특정 폼이 있는 주석을 사용하여 도구가 해당 주석과 그 앞에 나오는 소스 코드 요소에서 XML을 생성하도록 지시할 수 있습니다. 이러한 주석은 슬래시3개(§6.3.3) 또는 슬래시///와 별표 2개로 시작하는 Delimited_Comment(§6.3.3)로 시작하는 Single_Line_Comments(/**§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 문에 따라 네임스페이스 표시 유형을 준수해야 합니다. 제네릭 코드 요소의 경우 잘못된 XML을 생성하므로 일반 제네릭 구문(예: "List<T>")을 사용할 수 없습니다. 중괄호 대신 중괄호를 사용할 수 있습니다(예: "List{T}") 또는 XML 이스케이프 구문을 사용할 수 있습니다(예: "List<T>").태그
<summary>는 문서 뷰어에서 형식 또는 멤버에 대한 추가 정보를 표시하는 데 사용됩니다.태그에는
<include>외부 XML 파일의 정보가 포함됩니다.
문서 파일은 형식 및 멤버에 대한 전체 정보를 제공하지 않습니다(예: 형식 정보가 포함되지 않음). 형식 또는 멤버에 대한 이러한 정보를 얻으려면 설명서 파일을 형식 또는 멤버에 대한 리플렉션과 함께 사용해야 합니다.
D.3 권장 태그
D.3.1 일반
문서 생성기는 XML 규칙에 따라 유효한 태그를 수락하고 처리해야 합니다. 다음 태그는 사용자 설명서에서 일반적으로 사용되는 기능을 제공합니다. (물론 다른 태그도 가능합니다.)
| Tag | 참조 | 용도 |
|---|---|---|
<c> |
§D.3.2 | 코드와 유사한 글꼴로 텍스트 설정 |
<code> |
§D.3.3 | 하나 이상의 소스 코드 또는 프로그램 출력 줄 설정 |
<example> |
§D.3.4 | 예제 표시 |
<exception> |
§D.3.5 | 메서드가 throw할 수 있는 예외를 식별합니다. |
<include> |
§D.3.6 | 외부 파일의 XML 포함 |
<list> |
§D.3.7 | 목록 또는 테이블 만들기 |
<para> |
§D.3.8 | 텍스트에 구조체를 추가할 수 있도록 허용 |
<param> |
§D.3.9 | 메서드 또는 생성자에 대한 매개 변수 설명 |
<paramref> |
§D.3.10 | 단어가 매개 변수 이름인지 확인 |
<permission> |
§D.3.11 | 멤버의 보안 접근성 문서화 |
<remarks> |
§D.3.12 | 형식에 대한 추가 정보 설명 |
<returns> |
§D.3.13 | 메서드의 반환 값 설명 |
<see> |
§D.3.14 | 링크 지정 |
<seealso> |
§D.3.15 | 참고 항목 생성 |
<summary> |
§D.3.16 | 형식 또는 형식의 멤버 설명 |
<typeparam> |
§D.3.17 | 제네릭 형식 또는 메서드에 대한 형식 매개 변수 설명 |
<typeparamref> |
§D.3.18 | 단어가 형식 매개 변수 이름인지 확인 |
<value> |
§D.3.19 | 속성 설명 |
D.3.2 <c>
이 태그는 설명 내의 텍스트 조각을 코드 블록에 사용되는 것과 같은 특수 글꼴로 설정해야 함을 나타내는 메커니즘을 제공합니다. 실제 코드 줄의 경우 (§D.3.3)를 사용합니다 <code> .
구문:
<c>text</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 <예제>
이 태그를 사용하면 주석 내의 예제 코드에서 메서드 또는 다른 라이브러리 멤버를 사용하는 방법을 지정할 수 있습니다. 일반적으로 태그(§D.3.3)도 사용합니다 <code> .
구문:
<example>description</example>
예제:
예제는 (§D.3.3)를 참조하세요 <code> .
D.3.5 <예외>
이 태그는 메서드가 throw할 수 있는 예외를 문서화하는 방법을 제공합니다.
구문:
<exception cref="멤버">설명</exception>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
cref="멤버는 멤버"의 이름입니다. 설명서 생성기는 지정된 멤버가 있는지 확인하고 설명서 파일의 정식 요소 이름으로 멤버를 변환합니다.- 설명 은 예외가 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 문서여야 하며, 해당 문서에서 포함할 XML을 지정하기 위해 XPath 식이 해당 문서에 적용됩니다. <include> 그런 다음 태그를 외부 문서에서 선택한 XML로 바꿉습니다.
구문:
<include file="filename" path="xpath" />
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
file="filename"은 외부 XML 파일의 파일 이름입니다. 파일 이름은 포함 태그가 포함된 파일을 기준으로 해석됩니다.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> 할 수 있습니다. (테이블을 정의할 때 제목에서 용어에 대한 항목만 제공하면 됩니다.)
목록의 각 항목은 <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>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 용어는 정의에 설명되어 있는 정의 용어입니다.
- 설명은 글머리 기호 또는 번호 매기기 목록의 항목이거나 용어의 정의입니다.
예제:
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 <para>
이 태그는 (§D.3.16) 또는 <returns> (§D.3.13)과 같은 <summary> 다른 태그 내에서 사용하기 위한 것이며 구조체를 텍스트에 추가할 수 있도록 허용합니다.
구문:
<para>content</para>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 콘텐츠 는 단락의 텍스트입니다.
예제:
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>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 이름은 매개 변수의 이름입니다.
- 설명 은 매개 변수에 대한 설명입니다.
예제:
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>
이 태그는 단어가 매개 변수임을 나타내는 데 사용됩니다. 설명서 파일을 처리하여 이 매개 변수의 형식을 고유하게 지정할 수 있습니다.
구문:
<paramref 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>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 멤버는 멤버 의 이름입니다. 설명서 생성기는 지정된 코드 요소가 있는지 확인하고 멤버를 설명서 파일의 정식 요소 이름으로 변환합니다.
- 설명 은 멤버에 대한 액세스에 대한 설명입니다.
예제:
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>description</remarks>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 설명 은 설명의 텍스트입니다.
예제:
/// <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>description</returns>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 설명 은 반환 값에 대한 설명입니다.
예제:
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 cref="멤버" href="URL" langword="키워드" />
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 멤버는 멤버 의 이름입니다. 설명서 생성기는 지정된 코드 요소가 있는지 확인하고 생성된 설명서 파일의 요소 이름으로 멤버를 변경합니다.
- 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 <seealso>
이 태그를 사용하면 참고 하위 항목에 대한 항목을 생성할 수 있습니다. (§D.3.14)를 사용하여 <see> 텍스트 내에서 링크를 지정합니다.
구문:
<seealso cref="멤버" href="URL" />
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 멤버는 멤버 의 이름입니다. 설명서 생성기는 지정된 코드 요소가 있는지 확인하고 생성된 설명서 파일의 요소 이름으로 멤버를 변경합니다.
- 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>description</summary>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 설명 은 형식 또는 멤버의 요약입니다.
예제:
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>
이 태그는 제네릭 형식 또는 메서드에 대한 형식 매개 변수를 설명하는 데 사용됩니다.
구문:
<typeparam name="이름">설명</typeparam>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 이름은 형식 매개 변수의 이름입니다.
- 설명 은 형식 매개 변수에 대한 설명입니다.
예제:
/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T>
{
...
}
D.3.18 <typeparamref>
이 태그는 단어가 형식 매개 변수임을 나타내는 데 사용됩니다. 설명서 파일을 처리하여 이 형식 매개 변수의 형식을 고유하게 지정할 수 있습니다.
구문:
<typeparamref name="이름"/>
라는 설치 관리자 실행 파일에 포함됩니다. 여기서
- 이름은 형식 매개 변수의 이름입니다.
예제:
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 형식(예: 클래스, 대리자, 열거형, 인터페이스 및 구조체) ! 오류 문자열; 문자열의 나머지 부분에는 오류에 대한 정보가 제공됩니다. 예를 들어 설명서 생성기는 확인할 수 없는 링크에 대한 오류 정보를 생성합니다. 문자열의 두 번째 부분은 네임스페이스의 루트에서 시작하여 요소의 정규화된 이름입니다. 요소의 이름, 요소의 바깥쪽 형식 및 네임스페이스는 마침표로 구분됩니다. 항목 자체의 이름에 마침표가 있는 경우 # (U+0023) 문자로 바뀝니다. (이름에 이 문자가 있는 요소는 없다고 가정합니다.) 정규화된 이름의 형식 인수는 멤버가 제네릭 인터페이스의 멤버를 명시적으로 구현하는 경우 해당 인수를 둘러싼 "" 및 "
>"를 "<" 및 "{}" 문자로 바꿔 인코딩됩니다.인수가 있는 메서드 및 속성의 경우 인수 목록이 괄호로 묶인 다음을 수행합니다. 인수가 없는 경우 괄호는 생략됩니다. 인수는 쉼표로 구분됩니다. 각 인수의 인코딩은 다음과 같이 CLI 서명과 동일합니다.
- 인수는 다음과 같이 수정된 정규화된 이름을 기반으로 하는 설명서 이름으로 표시됩니다.
- 제네릭 형식을 나타내는 인수에는 추가된 "
'" 문자 뒤에 형식 매개 변수 수가 추가됩니다. - 또는
refout한정자가 있는in인수의@형식 이름은 다음과 같이 지정됩니다. 값으로 또는 통해params전달되는 인수에는 특별한 표기법이 없습니다. - 배열인 인수는 더 낮은 바운드
:크기,로[표시됩니다.,lowerbound:크기]여기서 쉼표 수는 순위가 1보다 낮고 각 차원의 하한과 크기(알려진 경우)는 10진수로 표시됩니다. 하한 또는 크기를 지정하지 않으면 생략됩니다. 특정 차원의 하한 및 크기를 생략하면 ":"도 생략됩니다. 가변 배열은 수준당 하나의 "[]"로 표시됩니다. 1차원 배열은 하한이 0(기본값)(§17.1)이면 하한을 생략합니다. - 포인터 형식이 아닌
void다른 인수는 다음 형식 이름을 사용하여*표현됩니다.void포인터는 형식 이름을System.Void사용하여 표시됩니다. - 형식에 정의된 제네릭 형식 매개 변수를 참조하는 인수는 "
`" 문자와 형식 매개 변수의 인덱스(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> { ... }
}
}
ID:
"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;
}
}
ID:
"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) { ... }
}
}
ID:
"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"
종료자
namespace Acme
{
class Widget : IProcess
{
~Widget() { ... }
}
}
ID:
"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) { ... }
}
}
ID:
"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 { ... } }
}
}
ID:
"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;
}
}
ID:
"E:Acme.Widget.AnEvent"
단항 연산자
namespace Acme
{
class Widget : IProcess
{
public static Widget operator+(Widget x) { ... }
}
}
ID:
"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"
사용되는 단항 연산자 함수 이름의 전체 집합은 다음과 같습니다. op_UnaryPlusop_UnaryNegationop_LogicalNotop_OnesComplementop_Incrementop_Decrementop_Trueop_False
이진 연산자
namespace Acme
{
class Widget : IProcess
{
public static Widget operator+(Widget x1, Widget x2) { ... }
}
}
ID:
"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"
사용되는 이진 연산자 함수 이름의 전체 집합은 다음과 같습니다. op_Additionop_Subtractionop_Multiplyop_Divisionop_Modulusop_BitwiseAndop_BitwiseOrop_ExclusiveOrop_LeftShiftop_RightShiftop_Equalityop_Inequalityop_LessThanop_LessThanOrEqualop_GreaterThanop_GreaterThanOrEqual
변환 연산 자는 후행 "~"에 이어 반환 형식을 갖습니다. 변환 연산자의 원본 또는 대상이 제네릭 형식인 경우 "<" 및 "">" 문자는 각각 "" 및 "{}" 문자로 바뀝니다.
namespace Acme
{
class Widget : IProcess
{
public static explicit operator int(Widget x) { ... }
public static implicit operator long(Widget x) { ... }
}
}
ID:
"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
다음은 위에 표시된 클래스 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>
정보 텍스트의 끝입니다.
ECMA C# draft specification