Opmerkingen bij bijlage D-documentatie

Deze bijlage is informatief.

D.1 Algemeen

C# biedt een mechanisme voor programmeurs om hun code te documenteren met behulp van een syntaxis voor opmerkingen die XML-tekst bevat. In broncodebestanden kunnen opmerkingen met een bepaald formulier worden gebruikt om een hulpprogramma te leiden om XML te produceren op basis van deze opmerkingen en de broncode-elementen die ze voorafgaan. Opmerkingen die een dergelijke syntaxis gebruiken, worden documentatieopmerkingen genoemd. Ze moeten direct voorafgaan aan een door de gebruiker gedefinieerd type (zoals een klasse, gemachtigde of interface) of een lid (zoals een veld, gebeurtenis, eigenschap of methode). Het hulpprogramma voor het genereren van XML wordt de documentatiegenerator genoemd. (Deze generator kan zijn, maar hoeft niet te zijn, de C#-compiler zelf.) De uitvoer die door de documentatiegenerator wordt geproduceerd, wordt het documentatiebestand genoemd. Een documentatiebestand wordt gebruikt als invoer voor een documentatieviewer; een hulpprogramma dat is bedoeld om een soort visuele weergave van typegegevens en de bijbehorende documentatie te produceren.

Een conforme C#-compiler is niet vereist om de syntaxis van documentatieopmerkingen te controleren; dergelijke opmerkingen zijn gewoon gewone opmerkingen. Een conforme compiler is echter toegestaan om een dergelijke controle uit te voeren.

Deze specificatie stelt voor dat een set standaardtags moet worden gebruikt in documentatieopmerkingen, maar het gebruik van deze tags is niet vereist en andere tags kunnen indien gewenst worden gebruikt, zolang de regels van goed opgemaakte XML worden gevolgd. Voor C#-implementaties die gericht zijn op de CLI, biedt het ook informatie over de documentatiegenerator en de indeling van het documentatiebestand. Er wordt geen informatie gegeven over de documentatieviewer.

Inleiding D.2

Opmerkingen met een bepaald formulier kunnen worden gebruikt om een hulpprogramma te leiden om XML te produceren op basis van deze opmerkingen en de broncode-elementen die ze voorafgaan. Dergelijke opmerkingen zijn Single_Line_Comment s (§6.3.3) die beginnen met drie slashes (///) of Delimited_Comments (§6.3.3) die beginnen met een slash en twee sterretjes (/**). Ze moeten direct voorafgaan aan een door de gebruiker gedefinieerd type of een lid dat ze aantekeningen maken. Kenmerksecties (§22.3) worden beschouwd als onderdeel van declaraties, dus documentatieopmerkingen moeten voorafgaan aan kenmerken die zijn toegepast op een type of lid.

Voor exposerende doeleinden wordt de indeling van documentopmerkingen hieronder weergegeven als twee grammaticaregels: Single_Line_Doc_Comment en Delimited_Doc_Comment. Deze regels maken echter geen deel uit van de C#-grammatica, maar ze vertegenwoordigen echter specifieke indelingen van respectievelijk Single_Line_Comment en Delimited_Comment lexerregels.

Syntaxis:

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

Als er in een Single_Line_Doc_Comment een spatieteken is dat volgt /// op elk van de Single_Line_Doc_Comments naast de huidige Single_Line_Doc_Comment, wordt dat witruimteteken niet opgenomen in de XML-uitvoer.

Als in een Delimited_Doc_Comment het eerste niet-witruimteteken op de tweede regel een STERRETJE is en hetzelfde patroon van optionele spaties en een ASTERISK-teken wordt herhaald aan het begin van elk van de regels in de Delimited_Doc_Comment, worden de tekens van het herhaalde patroon niet opgenomen in de XML-uitvoer. Het patroon kan spaties bevatten na, evenals eerder, het ASTERISK-teken .

Voorbeeld:

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

De tekst in documentatieopmerkingen moet goed worden opgemaakt volgens de regels van XML (http://www.w3.org/TR/REC-xml). Als de XML niet goed is gevormd, wordt er een waarschuwing gegenereerd en bevat het documentatiebestand een opmerking waarin staat dat er een fout is opgetreden.

Hoewel ontwikkelaars vrij zijn om hun eigen set tags te maken, wordt een aanbevolen set gedefinieerd in §D.3. Sommige van de aanbevolen tags hebben speciale betekenissen:

• De <param> tag wordt gebruikt om parameters te beschrijven. Als een dergelijke tag wordt gebruikt, moet de documentatiegenerator controleren of de opgegeven parameter bestaat en of alle parameters worden beschreven in documentatieopmerkingen. Als deze verificatie mislukt, geeft de documentatiegenerator een waarschuwing.

• Het cref kenmerk kan worden gekoppeld aan elke tag om een verwijzing naar een code-element op te geven. De documentatiegenerator moet controleren of dit code-element bestaat. Als de verificatie mislukt, geeft de documentatiegenerator een waarschuwing. Wanneer u op zoek bent naar een naam die in een cref kenmerk wordt beschreven, moet de documentatiegenerator de zichtbaarheid van de naamruimte respecteren op basis van het gebruik van instructies die in de broncode worden weergegeven. Voor code-elementen die algemeen zijn, kan de normale algemene syntaxis (bijvoorbeeld 'List<T>) niet worden gebruikt omdat het ongeldige XML produceert. Accolades kunnen worden gebruikt in plaats van haakjes (bijvoorbeeld; 'List{T}) of de syntaxis van de XML-escape kan worden gebruikt (bijvoorbeeld 'List<T>).'

• De <summary> tag is bedoeld om door een documentatieviewer te worden gebruikt om aanvullende informatie over een type of lid weer te geven.

• De <include> tag bevat informatie uit een extern XML-bestand.

Houd er rekening mee dat het documentatiebestand geen volledige informatie bevat over het type en de leden (het bevat bijvoorbeeld geen typegegevens). Als u dergelijke informatie over een type of lid wilt ophalen, moet het documentatiebestand worden gebruikt in combinatie met weerspiegeling van het type of lid.

D.3 Aanbevolen tags

D.3.1 Algemeen

De documentatiegenerator moet elke tag accepteren en verwerken die geldig is volgens de regels van XML. De volgende tags bieden veelgebruikte functionaliteit in gebruikersdocumentatie. (Natuurlijk zijn er andere tags mogelijk.)

Tag	Verwijzing	Doel
<c>	§D.3.2	Tekst instellen in een codeachtig lettertype
<code>	§D.3.3	Een of meer regels broncode of programma-uitvoer instellen
<example>	§D.3.4	Een voorbeeld aangeven
<exception>	§D.3.5	Identificeert de uitzonderingen die een methode kan genereren
<include>	§D.3.6	Bevat XML uit een extern bestand
<list>	§D.3.7	Een lijst of tabel maken
<para>	§D.3.8	Toestaan dat structuur wordt toegevoegd aan tekst
<param>	§D.3.9	Een parameter voor een methode of constructor beschrijven
<paramref>	§D.3.10	Identificeren dat een woord een parameternaam is
<permission>	§D.3.11	De toegankelijkheid van een lid documenteer
<remarks>	§D.3.12	Aanvullende informatie over een type beschrijven
<returns>	§D.3.13	De retourwaarde van een methode beschrijven
<see>	§D.3.14	Een koppeling opgeven
<seealso>	§D.3.15	Een zie ook-item genereren
<summary>	§D.3.16	Een type of lid van een type beschrijven
<typeparam>	§D.3.17	Een typeparameter voor een algemeen type of methode beschrijven
<typeparamref>	§D.3.18	Bepalen of een woord een typeparameternaam is
<value>	§D.3.19	Een eigenschap beschrijven

D.3.2 <c>

Deze tag biedt een mechanisme om aan te geven dat een fragment van tekst in een beschrijving moet worden ingesteld in een speciaal lettertype, zoals dat wordt gebruikt voor een codeblok. Gebruik <code> voor regels met werkelijke code (§D.3.3).

Syntaxis:

<c>tekst</c>

Voorbeeld:

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

D.3.3-code <>

Deze tag wordt gebruikt om een of meer regels broncode of programma-uitvoer in te stellen in een speciaal lettertype. Gebruik <c> voor kleine codefragmenten in verhaal (§D.3.2).

Syntaxis:

<code>broncode of programma-uitvoer</code>

Voorbeeld:

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

Voorbeeld van D.3.4 <>

Met deze tag kunt u voorbeeldcode binnen een opmerking opgeven hoe een methode of ander bibliotheeklid kan worden gebruikt. Normaal gesproken zou dit ook betrekking hebben op het gebruik van de tag <code> (§D.3.3).

Syntaxis:

<example>beschrijving</example>

Voorbeeld:

Zie <code> (§D.3.3) voor een voorbeeld.

D.3.5-uitzondering <>

Deze tag biedt een manier om de uitzonderingen te documenteren die een methode kan genereren.

Syntaxis:

<exception cref="beschrijving van lid"></exception>

waar

• cref="lid" is de naam van een lid. De documentatiegenerator controleert of het opgegeven lid bestaat en vertaalt het lid naar de canonieke elementnaam in het documentatiebestand.
• beschrijving is een beschrijving van de omstandigheden waarin de uitzondering wordt gegenereerd.

Voorbeeld:

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

Met deze tag kunt u informatie opnemen uit een XML-document dat zich buiten het broncodebestand bevindt. Het externe bestand moet een goed opgemaakt XML-document zijn en er wordt een XPath-expressie toegepast op dat document om op te geven welke XML van dat document moet worden opgenomen. De <include> tag wordt vervolgens vervangen door de geselecteerde XML uit het externe document.

Syntaxis:

<include file="bestandsnaam" path="xpath" />

waar

• file="bestandsnaam" is de bestandsnaam van een extern XML-bestand. De bestandsnaam wordt geïnterpreteerd ten opzichte van het bestand dat de include-tag bevat.
• path="xpath" is een XPath-expressie die een deel van de XML in het externe XML-bestand selecteert.

Voorbeeld:

Als de broncode een declaratie bevat zoals:

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

en het externe bestand 'docs.xml' had de volgende inhoud:

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

dan wordt dezelfde documentatie uitgevoerd alsof de broncode het volgende bevat:

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

D.3.7-lijst <>

Deze tag wordt gebruikt om een lijst of tabel met items te maken. Het kan een <listheader> blok bevatten om de koprij van een tabel of definitielijst te definiëren. (Bij het definiëren van een tabel moet alleen een vermelding voor de term in de kop worden opgegeven.)

Elk item in de lijst wordt opgegeven met een <item> blok. Bij het maken van een definitielijst moeten zowel de term als de beschrijving worden opgegeven. Voor een tabel, lijst met opsommingstekens of genummerde lijsten hoeft u alleen een beschrijving op te geven.

Syntaxis:

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

waar

• term is de term die moet worden gedefinieerd, waarvan de definitie in beschrijving is.
• beschrijving is een item in een lijst met opsommingstekens of een genummerde lijst, of de definitie van een term.

Voorbeeld:

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

Deze tag is bedoeld voor gebruik in andere tags, zoals <summary> (§D.3.16) of <returns> (§D.3.13) en staat toe dat de structuur aan tekst kan worden toegevoegd.

Syntaxis:

<para>tevreden</para>

waar

• inhoud is de tekst van de alinea.

Voorbeeld:

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>

Deze tag wordt gebruikt om een parameter te beschrijven voor een methode, constructor of indexeerfunctie.

Syntaxis:

<param name="naambeschrijving"></param>

waar

• naam is de naam van de parameter.
• beschrijving is een beschrijving van de parameter.

Voorbeeld:

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>

Deze tag wordt gebruikt om aan te geven dat een woord een parameter is. Het documentatiebestand kan op een afzonderlijke manier worden verwerkt om deze parameter op te maken.

Syntaxis:

<paramref name="name"/>

waar

• naam is de naam van de parameter.

Voorbeeld:

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

Met deze tag kan de toegankelijkheid van een lid worden gedocumenteerd.

Syntaxis:

<permission cref="beschrijving van lid"></permission>

waar

• lid is de naam van een lid. De documentatiegenerator controleert of het opgegeven code-element bestaat en vertaalt lid naar de canonieke elementnaam in het documentatiebestand.
• beschrijving is een beschrijving van de toegang tot het lid.

Voorbeeld:

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

D.3.12 <opmerkingen>

Deze tag wordt gebruikt om extra informatie over een type op te geven. Gebruik <summary> (§D.3.16) om het type zelf en de leden van een type te beschrijven.

Syntaxis:

<remarks>beschrijving</remarks>

waar

• beschrijving is de tekst van de opmerking.

Voorbeeld:

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

D.3.13 <retourneert>

Deze tag wordt gebruikt om de retourwaarde van een methode te beschrijven.

Syntaxis:

<returns>beschrijving</returns>

waar

• beschrijving is een beschrijving van de retourwaarde.

Voorbeeld:

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

Met deze tag kan een koppeling in tekst worden opgegeven. Gebruik <seealso> (§D.3.15) om tekst aan te geven die moet worden weergegeven in een zie ook subclause.

Syntaxis:

<see cref="trefwoord lid-URL" href="" langword="" />

waar

• lid is de naam van een lid. De documentatiegenerator controleert of het opgegeven code-element bestaat en wijzigt het lid in de naam van het element in het gegenereerde documentatiebestand.
• URL is een verwijzing naar een externe bron.
• Langword is een woord dat op een of andere manier moet worden gemarkeerd.

Voorbeeld:

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>

Met deze tag kan een vermelding worden gegenereerd voor de subclause Zie ook . Gebruik <see> (§D.3.14) om een koppeling op te geven vanuit tekst.

Syntaxis:

<seealso cref="lid-URL" href="" />

waar

• lid is de naam van een lid. De documentatiegenerator controleert of het opgegeven code-element bestaat en wijzigt het lid in de naam van het element in het gegenereerde documentatiebestand.
• URL is een verwijzing naar een externe bron.

Voorbeeld:

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

Samenvatting D.3.16 <>

Deze tag kan worden gebruikt om een type of lid van een type te beschrijven. Gebruik <remarks> (§D.3.12) om extra informatie over het type of lid op te geven.

Syntaxis:

<summary>beschrijving</summary>

waar

• beschrijving is een samenvatting van het type of lid.

Voorbeeld:

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>

Deze tag wordt gebruikt om een typeparameter voor een algemeen type of methode te beschrijven.

Syntaxis:

<typeparam name="naambeschrijving"></typeparam>

waar

• naam is de naam van de typeparameter.
• beschrijving is een beschrijving van de typeparameter.

Voorbeeld:

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

D.3.18 <typeparamref>

Deze tag wordt gebruikt om aan te geven dat een woord een typeparameter is. Het documentatiebestand kan op een duidelijke manier worden verwerkt om deze typeparameter op te maken.

Syntaxis:

<typeparamref name="name"/>

waar

• naam is de naam van de typeparameter.

Voorbeeld:

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

D.3.19-waarde <>

Met deze tag kan een eigenschap worden beschreven.

Syntaxis:

<value>beschrijving van eigenschap</value>

waar

• beschrijving van eigenschap is een beschrijving voor de eigenschap.

Voorbeeld:

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

D.4 Het documentatiebestand verwerken

D.4.1 Algemeen

De volgende informatie is bedoeld voor C#-implementaties die gericht zijn op de CLI.

De documentatiegenerator genereert een id-tekenreeks voor elk element in de broncode die is getagd met een opmerking bij de documentatie. Deze id-tekenreeks identificeert een bronelement op unieke wijze. Een documentatieviewer kan een id-tekenreeks gebruiken om het bijbehorende item te identificeren waarop de documentatie van toepassing is.

Het documentatiebestand is geen hiërarchische weergave van de broncode; in plaats daarvan is het een platte lijst met een gegenereerde id-tekenreeks voor elk element.

Tekenreeksindeling D.4.2

De documentatiegenerator ziet de volgende regels wanneer de id-tekenreeksen worden gegenereerd:

• Er wordt geen witruimte in de tekenreeks geplaatst.

• Het eerste deel van de tekenreeks identificeert het type lid dat wordt gedocumenteerd, via één teken gevolgd door een dubbele punt. De volgende soorten leden worden gedefinieerd:

  Karakter	Beschrijving
  E	Gebeurtenis
  F	Veld
  M	Methode (inclusief constructors, finalizers en operators)
  N	Naamruimte
  P	Eigenschap (inclusief indexeerfuncties)
  T	Type (zoals klasse, gemachtigde, opsomming, interface en struct)
  !	Fouttekenreeks; de rest van de tekenreeks bevat informatie over de fout. De documentatiegenerator genereert bijvoorbeeld foutinformatie voor koppelingen die niet kunnen worden opgelost.

• Het tweede deel van de tekenreeks is de volledig gekwalificeerde naam van het element, te beginnen bij de hoofdmap van de naamruimte. De naam van het element, het bijbehorende type(en) en de naamruimte worden gescheiden door puntjes. Als de naam van het item zelf punten bevat, worden deze vervangen door #-tekens (U+0023). (Er wordt van uitgegaan dat er geen element dit teken in de naam heeft.) Typ argumenten in de volledig gekwalificeerde naam, want wanneer een lid expliciet een lid van een algemene interface implementeert, worden gecodeerd door de '<' en '>' eromheen te vervangen door de tekens '{' en '}.

• Voor methoden en eigenschappen met argumenten volgt de lijst met argumenten, tussen haakjes. Voor degenen zonder argumenten worden de haakjes weggelaten. De argumenten worden gescheiden door komma's. De codering van elk argument is als volgt hetzelfde als een CLI-handtekening:

  • Argumenten worden vertegenwoordigd door de naam van de documentatie, die is gebaseerd op de volledig gekwalificeerde naam, gewijzigd als volgt:
    • Argumenten die algemene typen vertegenwoordigen, hebben een toegevoegd ''' teken gevolgd door het aantal typeparameters
    • Argumenten met de innaam out of ref wijzigingsfunctie hebben een @ volgende typenaam. Argumenten die zijn doorgegeven door een waarde of via params een speciale notatie hebben geen speciale notatie.
    • Argumenten die matrices zijn, worden weergegeven als [ lagere grootte : , ... ,lowerbound : grootte ] waarbij het aantal komma's de rang lager is dan één en de ondergrenzen en grootte van elke dimensie, indien bekend, worden weergegeven in decimalen. Als er geen ondergrens of grootte is opgegeven, wordt deze weggelaten. Als de ondergrens en grootte voor een bepaalde dimensie worden weggelaten, wordt ook de ':' weggelaten. Gelabelde matrices worden vertegenwoordigd door één '[]' per niveau. Eéndimensionale matrices laten de ondergrens weg wanneer de ondergrens 0 is (de standaardwaarde) (§17.1).
    • Argumenten met andere typen aanwijzers dan void worden weergegeven met behulp van de * naam van het type. Een void aanwijzer wordt weergegeven met een typenaam van System.Void.
    • Argumenten die verwijzen naar algemene typeparameters die zijn gedefinieerd voor typen, worden gecodeerd met behulp van het teken '`' gevolgd door de op nul gebaseerde index van de typeparameter.
    • Argumenten die gebruikmaken van algemene typeparameters die zijn gedefinieerd in methoden, gebruiken een dubbele backtick "``" in plaats van de "`" die wordt gebruikt voor typen.
    • Argumenten die verwijzen naar samengestelde algemene typen worden gecodeerd met behulp van het algemene type, gevolgd door '{', gevolgd door een door komma's gescheiden lijst met typeargumenten, gevolgd door '}'.

Voorbeelden van id-tekenreeksen van D.4.3

In de volgende voorbeelden ziet u elk een fragment van C#-code, samen met de id-tekenreeks die is geproduceerd op basis van elk bronelement dat een opmerking over de documentatie kan maken:

Typen worden weergegeven met behulp van hun volledig gekwalificeerde naam, uitgebreid met algemene informatie:

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

Ids:

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

Velden worden vertegenwoordigd door hun volledig gekwalificeerde naam.

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

Ids:

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

Constructeurs

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

Ids:

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

Finalizers

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

Ids:

"M:Acme.Widget.Finalize"

Methoden

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

Ids:

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

Eigenschappen en indexeerfuncties

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

Ids:

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

Gebeurtenissen

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

Ids:

"E:Acme.Widget.AnEvent"

Unaire operators

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

Ids:

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

De volledige set unaire operatorfunctienamen die worden gebruikt, is als volgt: op_UnaryPlus, , op_UnaryNegationop_LogicalNot, op_OnesComplement, op_Increment, , op_Decrement, op_Trueen op_False.

Binaire operatoren

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

Ids:

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

De volledige set namen van binaire operatorfuncties die worden gebruikt, is als volgt: op_Addition, , op_Multiplyop_Subtraction, op_BitwiseOrop_Divisionop_ExclusiveOrop_BitwiseAndop_Modulus, , op_LeftShift, op_RightShiftop_LessThanOrEqualop_Inequalityop_LessThanop_Equality, en . op_GreaterThanop_GreaterThanOrEqual

Conversieoperators hebben een volgvolgend "~" gevolgd door het retourtype. Wanneer de bron of het doel van een conversieoperator een algemeen type is, worden de tekens '<' en '">' vervangen door respectievelijk de '{' en '}' tekens.

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

Ids:

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

D.5 Een voorbeeld

D.5.1 C#-broncode

In het volgende voorbeeld ziet u de broncode van een puntklasse:

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

Hier volgt de uitvoer die wordt geproduceerd door één documentatiegenerator wanneer de broncode voor klasse Pointwordt gegeven, zoals hierboven wordt weergegeven:

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

Einde van informatieve tekst.