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řed uživatelem definovaný typ (například třída, delegát nebo rozhraní) nebo člen (například pole, událost, vlastnost nebo metoda). 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 do 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é připomínky jsou Single_Line_Comment s (§6.3.3), které začínají třemi lomítky (///) nebo Delimited_Comments (§6.3.3), které začínají lomítkem a dvěma hvězdičkami (/**). Musí bezprostředně před uživatelem definovaný typ nebo člen, který označí. 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 účely expository se formát komentářů k dokumentu 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+ '/'
    ;

Pokud je v Single_Line_Doc_Comment znak prázdného znaku, který následuje za /// znaky v každé Single_Line_Doc_Comments vedle aktuálního Single_Line_Doc_Comment, pak tento znak prázdného znaku není součástí výstupu XML.

V Delimited_Doc_Comment platí, že pokud je první znak mezery na druhém řádku hvězdičkou a stejný vzor volitelných znaků prázdných znaků a znak ASTERISK se opakuje na začátku každého řádku v Delimited_Doc_Comment, nebudou znaky opakovaného vzoru 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 řídicí 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.

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

Tag	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 přístupnost zabezpečení č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án.

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>

stejná dokumentace je výstup, 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 <param>

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

Oprávnění D.3.11 <>

Tato značka umožňuje dokumentovat přístupnost 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 dílčím seznamu Viz také .

Syntaxe:

<see cref="klíčové slovo adresy URL" langword="člena" href="" />

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é se nějak zvýrazní.

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

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="adresa URL člena" href="" />

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

D.3.17 <typeparam>

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í žádné prázdné znaky.

• 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	Obor názvů
  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 počínaje kořenem oboru názvů. Název prvku, jeho ohraničující typy a obor názvů jsou odděleny tečkami. Pokud název položky obsahuje tečky, nahradí se znakem # (U+0023). (Předpokládá se, že žádný prvek nemá tento znak v názvu.) Do plně kvalifikovaného názvu zadejte argumenty, pokud člen explicitně implementuje člena obecného rozhraní, jsou kódovány tak, že nahradí "<" a ">" 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 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í inmodifikátor , out ref mají @ následující název typu. Argumenty předané hodnotou nebo prostřednictvím params nemají žádný zvláštní zápis.
    • Argumenty, které jsou matice, jsou reprezentovány jako [ nižší : velikost ... , ,lowerbound : velikost ] kde počet čárek je pořadí menší jedna a dolní mez a velikost každé dimenze, pokud je znám, jsou reprezentovány 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é ":". Jagged arrays are represented by one "[]" per level. 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 pomocí názvu System.Voidtypu .
    • 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é backtick "``" místo "`" použité 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_Modulusop_BitwiseAnd, op_RightShiftop_Equalityop_ExclusiveOrop_BitwiseOrop_LeftShift, op_Inequality, op_LessThan, , , op_LessThanOrEqualop_GreaterThana .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