Uwagi dokumentacji załącznika D

Niniejszy załącznik jest informacyjny.

D.1 Ogólne

Język C# zapewnia programistom mechanizm dokumentowania kodu przy użyciu składni komentarza zawierającej tekst XML. W plikach kodu źródłowego komentarze o określonym formularzu mogą służyć do kierowania narzędzia do tworzenia kodu XML z tych komentarzy i elementów kodu źródłowego, które poprzedzają. Komentarze korzystające z takiej składni są nazywane komentarzami do dokumentacji. Muszą natychmiast poprzedzać typ zdefiniowany przez użytkownika (taki jak klasa, delegat lub interfejs) lub składowy (na przykład pole, zdarzenie, właściwość lub metoda). Narzędzie do generowania kodu XML jest nazywane generatorem dokumentacji. (Ten generator może być, ale nie musi być, sam kompilator języka C#). Dane wyjściowe generowane przez generator dokumentacji są nazywane plikiem dokumentacji. Plik dokumentacji jest używany jako dane wejściowe przeglądarki dokumentacji. Narzędzie przeznaczone do tworzenia pewnego rodzaju wizualnego wyświetlania informacji o typie i skojarzonej z nią dokumentacji.

Zgodny kompilator języka C# nie jest wymagany do sprawdzania składni komentarzy dokumentacji; takie komentarze są po prostu zwykłymi komentarzami. Jednak zgodny kompilator może wykonać takie sprawdzanie.

Ta specyfikacja sugeruje zestaw standardowych tagów do użycia w komentarzach dokumentacji, ale użycie tych tagów nie jest wymagane, a inne tagi mogą być używane w razie potrzeby, o ile są przestrzegane reguły dobrze sformułowanego kodu XML. W przypadku implementacji języka C# przeznaczonych dla interfejsu wiersza polecenia udostępnia on również informacje o generatorze dokumentacji i formacie pliku dokumentacji. Przeglądarka dokumentacji nie zawiera żadnych informacji.

Wprowadzenie do D.2

Komentarze o określonym formularzu mogą służyć do kierowania narzędzia do tworzenia kodu XML z tych komentarzy i elementów kodu źródłowego, które poprzedzają. Takie komentarze są Single_Line_Comment s (§6.3.3), które zaczynają się od trzech ukośników (///) lub Delimited_Comments (§6.3.3), które zaczynają się ukośnikiem i dwoma gwiazdkami (/**). Muszą natychmiast poprzedzać typ zdefiniowany przez użytkownika lub element członkowski, którego dodają adnotacje. Sekcje atrybutów (§22.3) są uznawane za część deklaracji, dlatego komentarze dokumentacji muszą poprzedzać atrybuty stosowane do typu lub elementu członkowskiego.

W celach wykładnych format komentarzy dokumentów jest wyświetlany poniżej jako dwie reguły gramatyczne: Single_Line_Doc_Comment i Delimited_Doc_Comment. Jednak te reguły nie są częścią gramatyki języka C#, ale reprezentują one odpowiednio określone formaty reguł Single_Line_Comment i Delimited_Comment leksykatora.

Składnia:

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

W Single_Line_Doc_Comment, jeśli na każdym z Single_Line_Doc_Comments obok bieżącego Single_Line_Doc_Comment znajduje się znak /// Biały znak, znak biały nie jest uwzględniony w danych wyjściowych XML.

W Delimited_Doc_Comment, jeśli pierwszy znak inny niż biały w drugim wierszu jest znakiem ASTERISK i tym samym wzorcem opcjonalnych znaków odstępu, a znak GWIAZDKISK jest powtarzany na początku każdego wiersza w Delimited_Doc_Comment, znaki powtarzającego się wzorca nie są uwzględniane w danych wyjściowych XML. Wzorzec może zawierać znaki Biały znak po, a także przed znakiem ASTERISK .

Przykład:

/// <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() {...}
}

Tekst w komentarzach dokumentacji musi być dobrze sformułowany zgodnie z regułami xml (http://www.w3.org/TR/REC-xml). Jeśli kod XML jest źle sformułowany, zostanie wygenerowane ostrzeżenie, a plik dokumentacji będzie zawierać komentarz z informacją o napotkaniu błędu.

Mimo że deweloperzy mogą tworzyć własny zestaw tagów, zalecany zestaw jest zdefiniowany w §D.3. Niektóre z zalecanych tagów mają specjalne znaczenie:

• Tag <param> służy do opisywania parametrów. Jeśli taki tag jest używany, generator dokumentacji musi sprawdzić, czy określony parametr istnieje i czy wszystkie parametry są opisane w komentarzach dokumentacji. Jeśli taka weryfikacja zakończy się niepowodzeniem, generator dokumentacji wyświetla ostrzeżenie.

• Atrybut cref można dołączyć do dowolnego tagu, aby podać odwołanie do elementu kodu. Generator dokumentacji musi sprawdzić, czy ten element kodu istnieje. Jeśli weryfikacja zakończy się niepowodzeniem, generator dokumentacji wyświetla ostrzeżenie. Jeśli szukasz nazwy opisanej w atrybucie cref , generator dokumentacji musi uwzględniać widoczność przestrzeni nazw zgodnie z instrukcjami wyświetlanymi w kodzie źródłowym. W przypadku elementów kodu, które są ogólne, nie można użyć normalnej składni ogólnej (np. "List<T>"), ponieważ generuje nieprawidłowy kod XML. Nawiasy klamrowe mogą być używane zamiast nawiasów kwadratowych (np. "List{T}"), lub można użyć składni ucieczki XML (np. "List<T>").

• Tag <summary> ma być używany przez przeglądarkę dokumentacji do wyświetlania dodatkowych informacji o typie lub elemencie członkowskim.

• Tag <include> zawiera informacje z zewnętrznego pliku XML.

Należy pamiętać, że plik dokumentacji nie zawiera pełnych informacji o typie i elementach członkowskich (na przykład nie zawiera żadnych informacji o typie). Aby uzyskać takie informacje o typie lub elemencie członkowskim, należy użyć pliku dokumentacji w połączeniu z odbiciem typu lub elementu członkowskiego.

Zalecane tagi D.3

D.3.1 Ogólne

Generator dokumentacji musi zaakceptować i przetworzyć dowolny tag, który jest prawidłowy zgodnie z regułami XML. Poniższe tagi udostępniają często używane funkcje w dokumentacji użytkownika. (Oczywiście możliwe są inne tagi).

Tag	Odwołanie	Przeznaczenie
<c>	§D.3.2	Ustawianie tekstu w czcionce podobnej do kodu
<code>	§D.3.3	Ustawianie co najmniej jednego wiersza kodu źródłowego lub danych wyjściowych programu
<example>	§D.3.4	Wskazywanie przykładu
<exception>	§D.3.5	Identyfikuje wyjątki, które może zgłaszać metoda
<include>	§D.3.6	Zawiera kod XML z pliku zewnętrznego
<list>	§D.3.7	Tworzenie listy lub tabeli
<para>	§D.3.8	Zezwalaj na dodawanie struktury do tekstu
<param>	§D.3.9	Opisywanie parametru dla metody lub konstruktora
<paramref>	§D.3.10	Zidentyfikuj, że słowo jest nazwą parametru
<permission>	§D.3.11	Dokumentowanie ułatwień dostępu zabezpieczeń elementu członkowskiego
<remarks>	§D.3.12	Opisywanie dodatkowych informacji o typie
<returns>	§D.3.13	Opisywanie wartości zwracanej metody
<see>	§D.3.14	Określanie łącza
<seealso>	§D.3.15	Generowanie wpisu Zobacz również
<summary>	§D.3.16	Opisywanie typu lub elementu członkowskiego typu
<typeparam>	§D.3.17	Opisywanie parametru typu dla typu ogólnego lub metody
<typeparamref>	§D.3.18	Zidentyfikuj, że słowo jest nazwą parametru typu
<value>	§D.3.19	Opisywanie właściwości

D.3.2 <c>

Ten tag udostępnia mechanizm wskazujący, że fragment tekstu w opisie powinien być ustawiony w specjalnej czcionki, takiej jak używana dla bloku kodu. W przypadku wierszy rzeczywistego kodu użyj polecenia <code> (§D.3.3).

Składnia:

<c>text</c>

Przykład:

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

Kod D.3.3 <>

Ten tag służy do ustawiania co najmniej jednego wiersza kodu źródłowego lub danych wyjściowych programu w specjalnej czcionki. W przypadku małych fragmentów kodu w narracji należy użyć (<c>§D.3.2).

Składnia:

<code>kod źródłowy lub dane wyjściowe programu</code>

Przykład:

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)
    {
        ...
    }
}

Przykład D.3.4 <>

Ten tag umożliwia przykładowy kod w komentarzu, aby określić sposób użycia metody lub innego elementu członkowskiego biblioteki. Zazwyczaj wiązałoby się to również z użyciem tagu <code> (§D.3.3).

Składnia:

<example>opis</example>

Przykład:

Zobacz <code> przykład (§D.3.3).

Wyjątek D.3.5 <>

Ten tag umożliwia dokumentowanie wyjątków, które może zgłaszać metoda.

Składnia:

<exception cref="opis elementu członkowskiego"></exception>

where

• cref="element członkowski" jest nazwą elementu członkowskiego. Generator dokumentacji sprawdza, czy dany element członkowski istnieje i tłumaczy element członkowski na nazwę elementu kanonicznego w pliku dokumentacji.
• description to opis okoliczności, w których zgłaszany jest wyjątek.

Przykład:

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 <include>

Ten tag umożliwia dołączenie informacji z dokumentu XML zewnętrznego do pliku kodu źródłowego. Plik zewnętrzny musi być dobrze sformułowanym dokumentem XML, a wyrażenie XPath jest stosowane do tego dokumentu w celu określenia kodu XML z tego dokumentu do uwzględnienia. Następnie <include> tag jest zastępowany wybranym kodem XML z dokumentu zewnętrznego.

Składnia:

<include file="nazwa pliku" path="xpath" />

where

• file="nazwa pliku" to nazwa pliku zewnętrznego pliku XML. Nazwa pliku jest interpretowana względem pliku zawierającego tag dołączania.
• path="xpath" to wyrażenie XPath, które wybiera część kodu XML w zewnętrznym pliku XML.

Przykład:

Jeśli kod źródłowy zawiera deklarację podobną do:

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

plik zewnętrzny "docs.xml" miał następującą zawartość:

<?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>

wówczas ta sama dokumentacja jest danymi wyjściowymi, tak jak w przypadku, gdy zawarto kod źródłowy:

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

Lista D.3.7 <>

Ten tag służy do tworzenia listy lub tabeli elementów. Może zawierać <listheader> blok definiujące wiersz nagłówka tabeli lub listy definicji. (Podczas definiowania tabeli należy podać tylko wpis dla terminu w nagłówku).

Każdy element na liście jest określony z blokiem <item> . Podczas tworzenia listy definicji należy określić zarówno termin, jak i opis. Jednak w przypadku tabeli, listy punktowanej lub listy numerowanej należy określić tylko opis .

Składnia:

<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>

where

• termin to termin do zdefiniowania, którego definicja jest w opisie.
• description jest elementem na liście punktowanej lub numerowanej albo definicją terminu.

Przykład:

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>

Ten tag służy do użytku wewnątrz innych tagów, takich jak <summary> (§D.3.16) lub <returns> (§D.3.13) i zezwala na dodawanie struktury do tekstu.

Składnia:

<para>zawartość</para>

where

• zawartość jest tekstem akapitu.

Przykład:

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>

Ten tag służy do opisywania parametru metody, konstruktora lub indeksatora.

Składnia:

<param name="opis nazwy"></param>

where

• name to nazwa parametru.
• description to opis parametru.

Przykład:

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>

Ten tag służy do wskazywania, że słowo jest parametrem. Plik dokumentacji można przetworzyć w celu sformatowania tego parametru w odrębny sposób.

Składnia:

<paramref name="name"/>

where

• name to nazwa parametru.

Przykład:

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)
    {
        ...
    }
}

Uprawnienie D.3.11 <>

Ten tag umożliwia udokumentowanie ułatwień dostępu zabezpieczeń elementu członkowskiego.

Składnia:

<permission cref="opis elementu członkowskiego"></permission>

where

• element członkowski jest nazwą elementu członkowskiego. Generator dokumentacji sprawdza, czy dany element kodu istnieje i tłumaczy element członkowski na nazwę elementu kanonicznego w pliku dokumentacji.
• description to opis dostępu do elementu członkowskiego.

Przykład:

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

Uwagi D.3.12 <>

Ten tag służy do określania dodatkowych informacji o typie. Użyj <summary> (§D.3.16), aby opisać sam typ i składowe typu.

Składnia:

<remarks>opis</remarks>

where

• opis jest tekstem uwagi.

Przykład:

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

Zwraca wartość D.3.13 <>

Ten tag służy do opisywania wartości zwracanej metody.

Składnia:

<returns>opis</returns>

where

• description to opis wartości zwracanej.

Przykład:

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 <zobacz>

Ten tag umożliwia określenie linku w tekście. Użyj <seealso> polecenia (§D.3.15), aby wskazać tekst, który ma być wyświetlany w podklasie Zobacz również .

Składnia:

<see cref="słowo kluczowe adresu URL" langword="elementu członkowskiego" href="" />

where

• element członkowski jest nazwą elementu członkowskiego. Generator dokumentacji sprawdza, czy dany element kodu istnieje i zmienia element członkowski na nazwę elementu w wygenerowany plik dokumentacji.
• adres URL jest odwołaniem do źródła zewnętrznego.
• langword to słowo, które należy w jakiś sposób podkreślić.

Przykład:

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>

Ten tag umożliwia wygenerowanie wpisu dla podklasy Zobacz również . Użyj <see> (§D.3.14), aby określić link z wewnątrz tekstu.

Składnia:

<seealso cref="adres URL elementu członkowskiego" href="" />

where

• element członkowski jest nazwą elementu członkowskiego. Generator dokumentacji sprawdza, czy dany element kodu istnieje i zmienia element członkowski na nazwę elementu w wygenerowany plik dokumentacji.
• adres URL jest odwołaniem do źródła zewnętrznego.

Przykład:

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)
    {
        ...
    }
}

Podsumowanie D.3.16 <>

Ten tag może służyć do opisywania typu lub elementu członkowskiego typu. Użyj <remarks> (§D.3.12), aby określić dodatkowe informacje o typie lub elemencie członkowskim.

Składnia:

<summary>opis</summary>

where

• description to podsumowanie typu lub elementu członkowskiego.

Przykład:

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>

Ten tag służy do opisywania parametru typu dla typu ogólnego lub metody.

Składnia:

<typeparam name="opis nazwy"></typeparam>

where

• name to nazwa parametru typu.
• description to opis parametru typu.

Przykład:

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

D.3.18 <typeparamref>

Ten tag służy do wskazywania, że wyraz jest parametrem typu. Plik dokumentacji można przetworzyć w celu sformatowania tego parametru typu w inny sposób.

Składnia:

<typeparamref name="name"/>

where

• name to nazwa parametru typu.

Przykład:

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)
    {
        ...
    }
}

Wartość D.3.19 <>

Ten tag umożliwia opisanie właściwości.

Składnia:

<value>opis właściwości</value>

where

• opis właściwości to opis właściwości.

Przykład:

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

D.4 Przetwarzanie pliku dokumentacji

D.4.1 Ogólne

Poniższe informacje są przeznaczone dla implementacji języka C# przeznaczonych dla interfejsu wiersza polecenia.

Generator dokumentacji generuje ciąg identyfikatora dla każdego elementu w kodzie źródłowym oznaczonym komentarzem dokumentacji. Ten ciąg identyfikatora jednoznacznie identyfikuje element źródłowy. Przeglądarka dokumentacji może użyć ciągu identyfikatora, aby zidentyfikować odpowiedni element, do którego ma zastosowanie dokumentacja.

Plik dokumentacji nie jest hierarchiczną reprezentacją kodu źródłowego; zamiast tego jest to płaska lista z wygenerowanym ciągiem identyfikatora dla każdego elementu.

Format ciągu identyfikatora D.4.2

Generator dokumentacji obserwuje następujące reguły podczas generowania ciągów identyfikatorów:

• W ciągu nie jest umieszczana biała spacja.

• Pierwsza część ciągu identyfikuje rodzaj udokumentowanego elementu członkowskiego za pomocą pojedynczego znaku, po którym następuje dwukropek. Zdefiniowane są następujące rodzaje elementów członkowskich:

  Znak	Opis
  E	Zdarzenie
  F	Pole
  M	Metoda (w tym konstruktory, finalizatory i operatory)
  N	Przestrzeń nazw
  P	Właściwość (w tym indeksatory)
  T	Typ (taki jak klasa, delegat, wyliczenie, interfejs i struktura)
  !	Ciąg błędu; pozostała część ciągu zawiera informacje o błędzie. Na przykład generator dokumentacji generuje informacje o błędach dla linków, których nie można rozpoznać.

• Druga część ciągu jest w pełni kwalifikowaną nazwą elementu, zaczynając od katalogu głównego przestrzeni nazw. Nazwa elementu, jego otaczające typy i przestrzeń nazw są oddzielone kropkami. Jeśli nazwa samego elementu zawiera kropki, są zastępowane znakami #(U+0023). (Zakłada się, że żaden element nie ma tego znaku w nazwie). Argumenty typu w w pełni kwalifikowanej nazwy, jeśli element członkowski jawnie implementuje element członkowski interfejsu ogólnego, są kodowane przez zastąpienie znaków "<" i ">" otaczających je znakami "{" i "}".

• W przypadku metod i właściwości z argumentami lista argumentów jest następująca, ujęta w nawiasy. Dla tych bez argumentów nawiasy są pomijane. Argumenty są oddzielone przecinkami. Kodowanie każdego argumentu jest takie samo jak podpis interfejsu wiersza polecenia w następujący sposób:

  • Argumenty są reprezentowane przez ich nazwę dokumentacji, która jest oparta na ich w pełni kwalifikowanej nazwie, zmodyfikowane w następujący sposób:
    • Argumenty reprezentujące typy ogólne mają dołączony znak "'", po którym następuje liczba parametrów typu
    • Argumenty z modyfikatorem inout lub ref mają następującą @ nazwę typu. Argumenty przekazywane przez wartość lub za pośrednictwem params nie mają specjalnej notacji.
    • Argumenty, które są tablicami, są reprezentowane jako [ mniejszy rozmiar , ruchu przychodzącego : ... ,lowerbound : rozmiar ] gdzie liczba przecinków jest rangą mniejszą, a dolne granice i rozmiar każdego wymiaru, jeśli jest znany, są reprezentowane w liczbach dziesiętnych. Jeśli nie określono mniejszej granicy lub rozmiaru, zostanie pominięty. Jeśli pominięto niższą granicę i rozmiar dla określonego wymiaru, również pominięto wartość ":". Tablice postrzępione są reprezentowane przez jeden "[]" na poziom. Tablice jednowymiarowe pomijają dolną granicę, gdy dolna granica to 0 (wartość domyślna) (§17.1).
    • Argumenty, które mają typy wskaźników inne niż void są reprezentowane przy użyciu następującej * nazwy typu. Wskaźnik void jest reprezentowany przy użyciu nazwy System.Voidtypu .
    • Argumenty odwołujące się do ogólnych parametrów typu zdefiniowanych w typach są kodowane przy użyciu znaku "`", po którym następuje indeks zerowy parametru typu.
    • Argumenty używające ogólnych parametrów typu zdefiniowanych w metodach używają podwójnego backtick "``" zamiast "`" używanego dla typów.
    • Argumenty odwołujące się do skonstruowanych typów ogólnych są kodowane przy użyciu typu ogólnego, a następnie "{", po którym następuje rozdzielona przecinkami lista argumentów typu, a następnie "}".

Przykłady ciągów identyfikatorów D.4.3

W poniższych przykładach pokazano fragment kodu języka C# wraz z ciągiem identyfikatora utworzonym z każdego elementu źródłowego, który może mieć komentarz do dokumentacji:

Typy są reprezentowane przy użyciu ich w pełni kwalifikowanej nazwy, rozszerzone o ogólne informacje:

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> { ... }
    }
}

Identyfikatory:

"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"

Pola są reprezentowane przez ich w pełni kwalifikowaną nazwę.

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;
    }
}

Identyfikatory:

"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"

Konstruktory

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

Identyfikatory:

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

Finalizatory

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

Identyfikatory:

"M:Acme.Widget.Finalize"

Metody

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) { ... } 
    }
}

Identyfikatory:

"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)"

Właściwości i indeksatory

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 { ... } }
    }
}

Identyfikatory:

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

Wydarzenia

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

Identyfikatory:

"E:Acme.Widget.AnEvent"

Operatory jednoargumentowe

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

Identyfikatory:

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

Pełny zestaw używanych nazw funkcji operatorów jednoargumentowych jest następujący: op_UnaryPlus, , op_Incrementop_OnesComplementop_LogicalNotop_Decrementop_UnaryNegation, op_True, i .op_False

Operatory binarne

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

Identyfikatory:

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

Pełny zestaw używanych nazw funkcji operatora binarnego jest następujący: op_Addition, , op_Multiplyop_LessThanOrEqualop_Equalityop_RightShiftop_Inequalityop_LeftShiftop_LessThanop_GreaterThanop_Subtractionop_Modulusop_GreaterThanOrEqualop_Divisionop_BitwiseAndop_BitwiseOrop_ExclusiveOri .

Operatory konwersji mają końcowy ciąg "~", po którym następuje typ zwracany. Jeśli źródło lub miejsce docelowe operatora konwersji jest typem ogólnym, znaki "<" i "">" są zastępowane odpowiednio znakami "{" i "}".

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

Identyfikatory:

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

D.5 Przykład

Kod źródłowy D.5.1 C#

W poniższym przykładzie pokazano kod źródłowy klasy 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);
    }
}

Wynikowy kod XML D.5.2

Poniżej przedstawiono dane wyjściowe generowane przez jeden generator dokumentacji, gdy podano kod źródłowy dla klasy Point, jak pokazano powyżej:

<?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>

Koniec tekstu informacyjnego.