Komentáře k dokumentaci k příloze D

Tato příloha je informativní.

D.1 Obecné

Jazyk C# poskytuje programátorům mechanismus pro dokumentování kódu pomocí syntaxe komentáře, která obsahuje text XML. V souborech zdrojového kódu lze komentáře s určitým formulářem použít k nasměrovat nástroj k vytvoření XML z těchto komentářů a elementů zdrojového kódu, které předchází. Komentáře používající takovou syntaxi se nazývají komentáře dokumentace. Musí bezprostředně předcházet uživatelsky definovanému typu (například třídě, delegátu nebo rozhraní) nebo členu (například poli, události, vlastnosti nebo metodě). Nástroj pro generování XML se nazývá generátor dokumentace. (Tento generátor může být, ale nemusí být samotný kompilátor jazyka C#.) Výstup vytvořený generátorem dokumentace se nazývá soubor dokumentace. Soubor dokumentace se používá jako vstup do prohlížeče dokumentace. Nástroj určený k vytvoření nějakého vizuálního zobrazení informací o typu a související dokumentaci.

Odpovídající kompilátor jazyka C# není nutný ke kontrole syntaxe komentářů dokumentace; takové komentáře jsou prostě běžné komentáře. Odpovídající kompilátor však může tuto kontrolu provést.

Tato specifikace navrhuje sadu standardních značek, které se mají použít v dokumentačních komentářích, ale použití těchto značek není povinné, a v případě potřeby se můžou použít další značky, pokud jsou dodržena pravidla dobře formátovaných xml. V případě implementací jazyka C# určených pro rozhraní příkazového řádku poskytuje také informace o generátoru dokumentace a formátu souboru dokumentace. Prohlížeč dokumentace neobsahuje žádné informace.

Úvod D.2

Komentáře s určitým formulářem lze použít k nasměrovat nástroj k vytvoření XML z těchto komentářů a elementů zdrojového kódu, které předchází. Takové komentáře jsou Single_Line_Comment (§6.3.3), které začínají třemi lomítky (///), nebo Delimited_Comment (§6.3.3), které začínají lomítkem a dvěma hvězdičkami (/**). Musí bezprostředně předcházet typ nebo člen definovaný uživatelem, který anotují. Oddíly atributů (§22.3) jsou považovány za součást prohlášení, takže komentáře k dokumentaci musí předcházet atributům použitým u typu nebo člena.

Pro vysvětlující účely se formát dokumentačních komentářů zobrazuje níže jako dvě gramatická pravidla: Single_Line_Doc_Comment a Delimited_Doc_Comment. Tato pravidla však nejsou součástí gramatiky jazyka C#, ale představují konkrétní formáty Single_Line_Comment a Delimited_Comment lexerových pravidel.

Syntaxe:

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

V Single_Line_Doc_Comment, pokud následuje znak prázdna za znaky /// v každém ze Single_Line_Doc_Comments sousedících s aktuálním Single_Line_Doc_Comment, pak tento znak prázdna není zahrnut do výstupu XML.

V komentáři Delimited_Doc_Comment platí, že pokud je prvním znakem nenulové mezery na druhém řádku hvězdička a stejný vzor volitelných mezer a hvězdičky se opakuje na začátku každého řádku v rámci Delimited_Doc_Comment, pak znaky tohoto opakovaného vzoru nebudou zahrnuty do výstupu XML. Vzor může obsahovat prázdné znaky za znakem ASTERISK i za znakem hvězdičky.

Příklad:

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

Text v dokumentačních komentářích musí být správně vytvořen podle pravidel XML (http://www.w3.org/TR/REC-xml). Pokud je XML špatně vytvořený, vygeneruje se upozornění a soubor dokumentace bude obsahovat komentář s informací, že došlo k chybě.

I když vývojáři mohou vytvářet vlastní sadu značek, doporučená sada je definována v §D.3. Některé z doporučených značek mají zvláštní význam:

• Značka <param> se používá k popisu parametrů. Pokud se použije taková značka, generátor dokumentace musí ověřit, že zadaný parametr existuje a zda jsou všechny parametry popsány v komentářích dokumentace. Pokud takové ověření selže, generátor dokumentace vydá upozornění.

• Atribut cref lze připojit k jakékoli značce, která poskytuje odkaz na prvek kódu. Generátor dokumentace musí ověřit, že tento prvek kódu existuje. Pokud se ověření nezdaří, generátor dokumentace vydá upozornění. Při hledání názvu popsaného v atributu cref musí generátor dokumentace respektovat viditelnost oboru názvů podle příkazů using zobrazených ve zdrojovém kódu. Pro obecné prvky kódu nelze použít normální obecnou syntaxi (např. "List<T>"), protože vytváří neplatný kód XML. Složené závorky lze použít místo závorek (např. "List{T}"), nebo lze použít escape syntaxi XML (např. "List<T>").

• Značka <summary> je určena k zobrazení dalších informací o typu nebo členovi prohlížečem dokumentace.

• Značka <include> obsahuje informace z externího souboru XML.

Pečlivě si všimněte, že soubor dokumentace neposkytuje úplné informace o typu a členech (například neobsahuje žádné informace o typu). Chcete-li získat takové informace o typu nebo členu, musí být soubor dokumentace použit ve spojení s reflexí typu nebo člena.

Částečný typ nebo částečná metoda lze deklarovat ve více částech, z nichž každý může být v jedné nebo více jednotkách kompilace a každý z nich může mít jeden nebo více komentářů k dokumentaci. Částečná metoda má obvykle "definování částečné deklarace" a "implementaci částečné deklarace".

U částečného typu jsou komentáře k dokumentu, které se vztahují přímo na tento typ, z každé jeho části zapsány do souboru dokumentace v určitém nezadaném pořadí.

Pro částečnou metodu:

• Pokud definující částečná deklarace nemá žádnou odpovídající implementaci částečné deklarace, všechny komentáře dokumentace k definici částečné deklarace budou ignorovány (protože tato deklarace bude odebrána).
• Jinak platí, že pokud prováděcí částečná deklarace obsahuje nějaké komentáře k dokumentaci, zapíšou se do souboru dokumentace a všechny komentáře dokumentace v definici částečné deklarace se ignorují.
• V opačném případě se všechny komentáře dokumentace v definici částečné deklarace zapíšou do souboru dokumentace.

D.3 Doporučené značky

D.3.1 Obecné

Generátor dokumentace musí přijmout a zpracovat všechny značky, které jsou platné podle pravidel XML. Následující značky poskytují běžně používané funkce v uživatelské dokumentaci. (Samozřejmě jsou možné i jiné značky.)

Značka	Odkaz	Účel
<c>	§D.3.2	Nastavení textu v písmu podobném kódu
<code>	§D.3.3	Nastavení jednoho nebo více řádků zdrojového kódu nebo výstupu programu
<example>	§D.3.4	Označení příkladu
<exception>	§D.3.5	Identifikuje výjimky, které může metoda vyvolat.
<include>	§D.3.6	Zahrnuje XML z externího souboru.
<list>	§D.3.7	Vytvoření seznamu nebo tabulky
<para>	§D.3.8	Povolit přidání struktury do textu
<param>	§D.3.9	Popis parametru pro metodu nebo konstruktor
<paramref>	§D.3.10	Určení, že slovo je název parametru
<permission>	§D.3.11	Zdokumentujte bezpečnostní přístup člena.
<remarks>	§D.3.12	Popis dalších informací o typu
<returns>	§D.3.13	Popis návratové hodnoty metody
<see>	§D.3.14	Zadání odkazu
<seealso>	§D.3.15	Vygenerování položky Viz také
<summary>	§D.3.16	Popis typu nebo člena typu
<typeparam>	§D.3.17	Popis parametru typu pro obecný typ nebo metodu
<typeparamref>	§D.3.18	Určení, že slovo je název parametru typu
<value>	§D.3.19	Popis vlastnosti

D.3.2 <c>

Tato značka poskytuje mechanismus, který označuje, že fragment textu v popisu by měl být nastaven ve speciálním písmu, jako je například použitý pro blok kódu. Pro řádky skutečného kódu použijte <code> (§D.3.3).

Syntaxe:

<c> Text</c>

Příklad:

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

Kód D.3.3 <>

Tato značka slouží k nastavení jednoho nebo více řádků zdrojového kódu nebo výstupu programu v určitém speciálním písmu. Pro malé fragmenty kódu v příběhu použijte <c> (§D.3.2).

Syntaxe:

<code> zdrojový kód nebo výstup programu</code>

Příklad:

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

Příklad D.3.4 <>

Tato značka umožňuje vzorový kód v komentáři k určení způsobu použití metody nebo jiného člena knihovny. Obvykle by to zahrnovalo také použití značky <code> (§D.3.3).

Syntaxe:

<example> popis</example>

Příklad:

Příklad najdete <code> v §D.3.3.

Výjimka D.3.5 <>

Tato značka poskytuje způsob, jak zdokumentovat výjimky, které může metoda vyvolat.

Syntaxe:

<exception cref=" popis člena"></exception>

kde

• cref=" člen" je jméno člena. Generátor dokumentace zkontroluje, jestli daný člen existuje, a přeloží ho na název kanonického prvku v souboru dokumentace.
• popis je popis okolností, za kterých je výjimka vyvolána.

Příklad:

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

Tato značka umožňuje zahrnutí informací z dokumentu XML, který je externí do souboru zdrojového kódu. Externí soubor musí být správně formátovaný dokument XML a výraz XPath se použije na tento dokument, aby bylo možné určit, který XML z dokumentu má obsahovat. Značka <include> se pak nahradí vybraným kódem XML z externího dokumentu.

Syntaxe:

<include file=" název souboru" path="xpath" />

kde

• file=" název souboru" je název externího souboru XML. Název souboru se interpretuje vzhledem k souboru, který obsahuje značku include.
• path=" xpath" je výraz XPath, který vybere část XML v externím souboru XML.

Příklad:

Pokud zdrojový kód obsahoval deklaraci jako:

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

a externí soubor "docs.xml" měl následující obsah:

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

Poté je stejná dokumentace vygenerována, jako kdyby zdrojový kód obsahoval:

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

Seznam D.3.7 <>

Tato značka slouží k vytvoření seznamu nebo tabulky položek. Může obsahovat <listheader> blok, který definuje řádek záhlaví tabulky nebo seznamu definic. (Při definování tabulky je nutné zadat pouze položku pro termín v nadpisu.)

Každá položka v seznamu je určena blokem <item> . Při vytváření seznamu definic musí být zadán termín i popis . Pro tabulku, seznam s odrážkami nebo číslovaný seznam je ale potřeba zadat jenom popis .

Syntaxe:

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

kde

• termín je termín, který se má definovat, jehož definice je v popisu.
• description je položka v seznamu s odrážkami nebo číslovaným seznamem nebo definice termínu.

Příklad:

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>

Tato značka se používá uvnitř jiných značek, například <summary> (§D.3.16) nebo <returns> (§D.3.13) a umožňuje přidat strukturu do textu.

Syntaxe:

<para> obsah</para>

kde

• obsah je text odstavce.

Příklad:

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

Tato značka slouží k popisu parametru pro metodu, konstruktor nebo indexer.

Syntaxe:

<param name=" popis názvu"></param>

kde

• name je název parametru.
• popis je popis parametru.

Příklad:

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>

Tato značka slouží k označení, že slovo je parametr. Soubor dokumentace lze zpracovat tak, aby tento parametr naformátoval určitým způsobem.

Syntaxe:

<paramref name=" Jméno"/>

kde

• name je název parametru.

Příklad:

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 <Oprávnění>

Tato značka umožňuje dokumentovat přístupové zabezpečení člena.

Syntaxe:

<permission cref=" popis člena"></permission>

kde

• člen je jméno člena. Generátor dokumentace zkontroluje, jestli daný prvek kódu existuje, a přeloží člena na název kanonického elementu v souboru dokumentace.
• popis je popis přístupu k členu.

Příklad:

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

D.3.12 <Poznámky>

Tato značka slouží k zadání dalších informací o typu. K popisu samotného typu a členů typu použijte <summary> (§D.3.16).

Syntaxe:

<remarks> popis</remarks>

kde

• popis je text poznámky.

Příklad:

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

Vrátí hodnotu D.3.13 <.>

Tato značka slouží k popisu návratové hodnoty metody.

Syntaxe:

<returns> popis</returns>

kde

• description je popis návratové hodnoty.

Příklad:

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

Tato značka umožňuje zadat odkaz v textu. Použijte <seealso> (§D.3.15) k označení textu, který se má zobrazit v pododstavci Viz také.

Syntaxe:

<see cref=" člen" href="url" langword="klíčové slovo" />

kde

• člen je jméno člena. Generátor dokumentace zkontroluje, jestli daný prvek kódu existuje, a změní člena na název elementu v generovaném souboru dokumentace.
• adresa URL je odkazem na externí zdroj.
• Langword je slovo, které by mělo být nějak zvýrazněno.

Příklad:

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 <viz také>

Tato značka umožňuje vygenerovat položku pro podkližku Viz také . Pomocí <see> (§D.3.14) můžete zadat odkaz z textu.

Syntaxe:

<seealso cref=" člen" href="url" />

kde

• člen je jméno člena. Generátor dokumentace zkontroluje, jestli daný prvek kódu existuje, a změní člena na název elementu v generovaném souboru dokumentace.
• adresa URL je odkazem na externí zdroj.

Příklad:

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

Souhrn D.3.16 <>

Tuto značku lze použít k popisu typu nebo člena typu. Pomocí <remarks> §D.3.12 můžete zadat dodatečné informace o typu nebo členu.

Syntaxe:

<summary> popis</summary>

kde

• popis je souhrn typu nebo člena.

Příklad:

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

Parametry typu D.3.17 <>

Tato značka slouží k popisu parametru typu pro obecný typ nebo metodu.

Syntaxe:

<typeparam name=" popis názvu"></typeparam>

kde

• name je název parametru typu.
• description je popis parametru typu.

Příklad:

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

D.3.18 <typeparamref>

Tato značka slouží k označení, že slovo je parametr typu. Soubor dokumentace lze zpracovat tak, aby formátoval tento parametr typu určitým způsobem.

Syntaxe:

<typeparamref name=" Jméno"/>

kde

• name je název parametru typu.

Příklad:

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

Hodnota D.3.19 <>

Tato značka umožňuje popis vlastnosti.

Syntaxe:

<value> popis vlastnosti</value>

kde

• popis vlastnosti je popis vlastnosti.

Příklad:

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

D.4 Zpracování souboru dokumentace

D.4.1 Obecné

Následující informace jsou určené pro implementace jazyka C#, jejichž cílem je rozhraní příkazového řádku.

Generátor dokumentace vygeneruje řetězec ID pro každý prvek ve zdrojovém kódu, který je označen komentářem k dokumentaci. Tento řetězec ID jednoznačně identifikuje zdrojový prvek. Prohlížeč dokumentace může pomocí řetězce ID identifikovat odpovídající položku, na kterou se dokumentace vztahuje.

Soubor dokumentace není hierarchickou reprezentací zdrojového kódu; je to plochý seznam s vygenerovaným řetězcem ID pro každý prvek.

Formát řetězce ID D.4.2

Generátor dokumentace při generování řetězců ID dodržuje následující pravidla:

• V řetězci není umístěna žádná mezera.

• První část řetězce identifikuje druh člena, který je dokumentován, prostřednictvím jednoho znaku následovaného dvojtečka. Jsou definovány následující typy členů:

  Znak	Popis
  E	Událost
  F	Pole
  M	Metoda (včetně konstruktorů, finalizátorů a operátorů)
  N	Jmenný prostor
  P	Vlastnost (včetně indexerů)
  T	Typ (například třída, delegát, výčet, rozhraní a struktura)
  !	Řetězec chyby; zbytek řetězce poskytuje informace o chybě. Generátor dokumentace například generuje informace o chybě pro odkazy, které nelze vyřešit.

• Druhá část řetězce je plně kvalifikovaný název elementu začínající u kořene oboru názvů. Název elementu, typy, které ho obklopují, a obor názvů je oddělen tečkami. Pokud název položky obsahuje tečky, jsou nahrazeny znaky # (U+0023). (Předpokládá se, že žádný prvek nemá tento znak v názvu.) Argumenty v plně kvalifikovaném názvu, když člen explicitně implementuje člena obecného rozhraní, jsou kódovány tak, že se nahradí znaky "<" a ">", které je obklopují, znaky "{" a "}".

• Pro metody a vlastnosti s argumenty následuje seznam argumentů uzavřený v závorkách. Pro ty bez argumentů jsou závorky vynechány. Argumenty jsou oddělené čárkami. Kódování každého argumentu je stejné jako podpis rozhraní příkazového řádku:

  • Argumenty jsou reprezentovány názvem jejich dokumentace, který je založen na jejich plně kvalifikovaném názvu a následně změněn následujícím způsobem:
    • Argumenty představující obecné typy mají připojený znak "'" následovaný počtem parametrů typu.
    • Argumenty, které mají in, out nebo ref modifikátor, mají @ za názvem svého typu. Argumenty předané hodnotou nebo prostřednictvím params nemají žádný zvláštní zápis.
    • Argumenty, které jsou pole, jsou reprezentovány jako [spodní hranice:velikost, … , lowerbound:velikost] kde počet čárek je o jednu menší než pořadí a dolní meze a velikost každé dimenze, pokud je známá, jsou vyjádřeny v desítkové soustavě. Pokud není zadána dolní mez nebo velikost, je vynechána. Pokud je vynechána dolní mez a velikost konkrétní dimenze, vynechá se také ":". Cik-cak pole jsou reprezentována jedním „[]“ na úroveň. Jednorozměrná pole vynechá dolní mez, pokud je dolní mez 0 (výchozí hodnota) (§17.1).
    • Argumenty, které mají jiné typy ukazatelů než void jsou reprezentovány pomocí * následujícího názvu typu. Ukazatel void je reprezentován typem System.Void.
    • Argumenty, které odkazují na parametry obecného typu definované u typů, jsou kódovány pomocí znaku "`" následovaného indexem založeným na nule parametru typu.
    • Argumenty, které používají parametry obecného typu definované v metodách, používají dvojité zpětné apostrofy "``" místo "`", které jsou použity pro typy.
    • Argumenty odkazující na vytvořené obecné typy jsou kódovány pomocí obecného typu, následované "{", následovaný čárkami oddělený seznam argumentů typu, následovaný "}".

Příklady řetězců ID D.4.3

Následující příklady ukazují fragment kódu jazyka C# spolu s řetězcem ID vytvořeným z každého zdrojového prvku, který může mít komentář k dokumentaci:

Typy jsou reprezentovány pomocí plně kvalifikovaného názvu rozšířeného o obecné informace:

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"

Pole jsou reprezentována jejich plně kvalifikovaným názvem.

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"

Konstruktory

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

Finalizační metody

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

Id:

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

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

Vlastnosti a indexery

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

Události

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

Id:

"E:Acme.Widget.AnEvent"

Unární operátory

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

Id:

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

Úplná sada názvů unárních operátorů se používá takto: op_UnaryPlus, op_UnaryNegation, , op_LogicalNot, op_OnesComplement, op_Increment, op_Decrement, op_True, a op_False.

Binární operátory

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

Id:

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

Úplná sada názvů binárních operátorů je následující: op_Addition, op_Subtraction, op_Multiply, op_Division, op_Modulus, op_BitwiseAnd, op_BitwiseOr, op_ExclusiveOr, op_LeftShift, op_RightShift, op_Equality, op_Inequality, op_LessThan, op_LessThanOrEqual, op_GreaterThan a op_GreaterThanOrEqual.

Operátory převodu mají koncovou "~" následovanou návratovým typem. Pokud je zdrojem nebo cílem operátoru převodu obecný typ, nahradí se znaky "<" a "">" znaky "{" a "}" v uvedeném pořadí.

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 Příklad

Zdrojový kód jazyka C#D.5.1

Následující příklad ukazuje zdrojový kód třídy 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 Výsledný XML

Zde je výstup vytvořený jedním generátorem dokumentace při zadání zdrojového kódu pro třídu Point, jak je znázorněno výše:

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

Konec informativního textu