Kommentarer till dokumentationen i bilaga D

Denna bilaga är informativ.

D.1 Allmänt

C# tillhandahåller en mekanism för programmerare att dokumentera sin kod med hjälp av en kommentarssyntax som innehåller XML-text. I källkodsfiler kan kommentarer med ett visst formulär användas för att dirigera ett verktyg för att skapa XML från dessa kommentarer och de källkodselement som de föregår. Kommentarer som använder sådan syntax kallas för dokumentationskommentar. De måste omedelbart föregå en användardefinierad typ (till exempel en klass, ett ombud eller ett gränssnitt) eller en medlem (till exempel ett fält, en händelse, en egenskap eller en metod). XML-genereringsverktyget kallas för dokumentationsgeneratorn. (Den här generatorn kan vara, men behöver inte vara, själva C#-kompilatorn.) Utdata som genereras av dokumentationsgeneratorn kallas dokumentationsfilen. En dokumentationsfil används som indata till en dokumentationsvisare, ett verktyg som är avsett att skapa någon form av visuell visning av typinformation och tillhörande dokumentation.

En kompatibel C#-kompilator krävs inte för att kontrollera syntaxen för dokumentationskommentarer. sådana kommentarer är helt enkelt vanliga kommentarer. En kompilator som uppfyller kraven kan dock utföra sådan kontroll.

Den här specifikationen föreslår en uppsättning standardtaggar som ska användas i dokumentationskommentare, men användning av dessa taggar krävs inte, och andra taggar kan användas om så önskas, så länge reglerna för välformulerad XML följs. För C#-implementeringar som riktar sig till CLI innehåller den även information om dokumentationsgeneratorn och formatet på dokumentationsfilen. Det finns ingen information om dokumentationsvisningsprogrammet.

Introduktion till D.2

Kommentarer med ett visst formulär kan användas för att dirigera ett verktyg för att skapa XML från dessa kommentarer och de källkodselement som de föregår. Sådana kommentarer är Single_Line_Comment s (§6.3.3) som börjar med tre snedstreck (///), eller Delimited_Comments (§6.3.3) som börjar med ett snedstreck och två asterisker (/**). De måste omedelbart föregå en användardefinierad typ eller en medlem som de kommenterar. Attributavsnitt (§22.3) betraktas som en del av deklarationerna, så dokumentationskommenter måste föregå attribut som tillämpas på en typ eller medlem.

I expository-syfte visas formatet för dokumentkommenterar nedan som två grammatikregler: Single_Line_Doc_Comment och Delimited_Doc_Comment. Dessa regler är dock inte en del av C#-grammatiken, utan representerar snarare specifika format för Single_Line_Comment respektive Delimited_Comment lexerregler.

Syntax:

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

I en Single_Line_Doc_Comment, om det finns ett blankstegstecken som följer /// tecknen på var och en av Single_Line_Doc_Comments intill den aktuella Single_Line_Doc_Comment, inkluderas inte det blankstegstecknet i XML-utdata.

Delimited_Doc_Comment Om det första icke-blankstegstecknet på den andra raden är en ASTERISK och samma mönster med valfria blankstegstecken och ett ASTERISK-tecken upprepas i början av var och en av raderna i Delimited_Doc_Comment, tas inte tecknen i det upprepade mönstret med i XML-utdata. Mönstret kan innehålla blankstegstecken efter, liksom tidigare, ASTERISK-tecknet .

Exempel:

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

Texten i dokumentationskommentarna måste vara väl utformad enligt XML-reglerna (http://www.w3.org/TR/REC-xml). Om XML-koden är dåligt utformad genereras en varning och dokumentationsfilen innehåller en kommentar om att ett fel påträffades.

Även om utvecklare kan skapa en egen uppsättning taggar definieras en rekommenderad uppsättning i §D.3. Några av de rekommenderade taggarna har särskilda betydelser:

• Taggen <param> används för att beskriva parametrar. Om en sådan tagg används måste dokumentationsgeneratorn kontrollera att den angivna parametern finns och att alla parametrar beskrivs i dokumentationskommentaren. Om sådan verifiering misslyckas utfärdar dokumentationsgeneratorn en varning.

• Attributet cref kan kopplas till valfri tagg för att ge en referens till ett kodelement. Dokumentationsgeneratorn måste kontrollera att det här kodelementet finns. Om verifieringen misslyckas utfärdar dokumentationsgeneratorn en varning. När du letar efter ett namn som beskrivs i ett cref attribut måste dokumentationsgeneratorn respektera synligheten för namnområdet enligt med hjälp av instruktioner som visas i källkoden. För kodelement som är generiska kan inte den normala allmänna syntaxen (t.ex. "List<T>") användas eftersom den genererar ogiltig XML. Klammerparenteser kan användas i stället för hakparenteser (t.ex. "List{T}"), eller xml-escape-syntaxen kan användas (t.ex. "List<T>").

• Taggen <summary> är avsedd att användas av en dokumentationsvisningsprogram för att visa ytterligare information om en typ eller medlem.

• Taggen <include> innehåller information från en extern XML-fil.

Observera noggrant att dokumentationsfilen inte innehåller fullständig information om typen och medlemmarna (till exempel innehåller den ingen typinformation). För att få sådan information om en typ eller medlem måste dokumentationsfilen användas tillsammans med reflektion över typen eller medlemmen.

D.3 Rekommenderade taggar

D.3.1 Allmänt

Dokumentationsgeneratorn måste godkänna och bearbeta alla taggar som är giltiga enligt XML-reglerna. Följande taggar innehåller vanliga funktioner i användardokumentationen. (Naturligtvis är andra taggar möjliga.)

Tag	Referens	Syfte
<c>	§D.3.2	Ange text i ett kodliknande teckensnitt
<code>	§D.3.3	Ange en eller flera rader med källkod eller programutdata
<example>	§D.3.4	Ange ett exempel
<exception>	§D.3.5	Identifierar de undantag som en metod kan utlösa
<include>	§D.3.6	Innehåller XML från en extern fil
<list>	§D.3.7	Skapa en lista eller tabell
<para>	§D.3.8	Tillåt att struktur läggs till i text
<param>	§D.3.9	Beskriva en parameter för en metod eller konstruktor
<paramref>	§D.3.10	Identifiera att ett ord är ett parameternamn
<permission>	§D.3.11	Dokumentera säkerhetstillgängligheten för en medlem
<remarks>	§D.3.12	Beskriva ytterligare information om en typ
<returns>	§D.3.13	Beskriva returvärdet för en metod
<see>	§D.3.14	Ange en länk
<seealso>	§D.3.15	Generera en se även-post
<summary>	§D.3.16	Beskriva en typ eller en medlem av en typ
<typeparam>	§D.3.17	Beskriva en typparameter för en allmän typ eller metod
<typeparamref>	§D.3.18	Identifiera att ett ord är ett typparameternamn
<value>	§D.3.19	Beskriva en egenskap

D.3.2 <c>

Den här taggen ger en mekanism som anger att ett fragment av text i en beskrivning ska anges i ett särskilt teckensnitt, till exempel det som används för ett kodblock. För rader med faktisk kod använder du <code> (§D.3.3).

Syntax:

<c>text</c>

Exempel:

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

D.3.3-kod <>

Den här taggen används för att ange en eller flera rader med källkod eller programutdata i ett särskilt teckensnitt. För små kodfragment i narrativ använder du <c> (§D.3.2).

Syntax:

<code>källkod eller programutdata</code>

Exempel:

public class Point
{
    /// <summary>
    /// This method changes the point's location by the given x- and y-offsets.
    /// <example>
    /// For example:
    /// <code>
    /// Point p = new Point(3,5);
    /// p.Translate(-1,3);
    /// </code>
    /// results in <c>p</c>'s having the value (2,8).
    /// </example>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.4-exempel <>

Den här taggen tillåter exempelkod i en kommentar för att ange hur en metod eller annan biblioteksmedlem kan användas. Vanligtvis skulle detta också innebära användning av taggen <code> (§D.3.3) också.

Syntax:

<example>beskrivning</example>

Exempel:

Se <code> (§D.3.3) för ett exempel.

D.3.5-undantag <>

Med den här taggen kan du dokumentera de undantag som en metod kan utlösa.

Syntax:

<exception cref="medlemsbeskrivning"></exception>

där

• cref="medlem" är namnet på en medlem. Dokumentationsgeneratorn kontrollerar att den angivna medlemmen finns och översätter medlemmen till det kanoniska elementnamnet i dokumentationsfilen.
• beskrivning är en beskrivning av de omständigheter under vilka undantaget utlöses.

Exempel:

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

Med den här taggen kan du inkludera information från ett XML-dokument som är externt till källkodsfilen. Den externa filen måste vara ett välformat XML-dokument och ett XPath-uttryck tillämpas på dokumentet för att ange vilken XML från dokumentet som ska inkluderas. Taggen <include> ersätts sedan med den markerade XML-koden från det externa dokumentet.

Syntax:

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

där

• file="filename" är filnamnet för en extern XML-fil. Filnamnet tolkas i förhållande till filen som innehåller inkluderingstaggen.
• path="xpath" är ett XPath-uttryck som väljer en del av XML-koden i den externa XML-filen.

Exempel:

Om källkoden innehåller en deklaration som:

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

och den externa filen "docs.xml" hade följande innehåll:

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

då är samma dokumentation utdata som om källkoden innehöll:

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

D.3.7-lista <>

Den här taggen används för att skapa en lista eller tabell med objekt. Den kan innehålla ett <listheader> block för att definiera rubrikraden i antingen en tabell eller en definitionslista. (När du definierar en tabell behöver endast en post för termen i rubriken anges.)

Varje objekt i listan anges med ett <item> block. När du skapar en definitionslista måste både term och beskrivning anges. För en tabell, punktlista eller numrerad lista behöver dock endast en beskrivning anges.

Syntax:

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

där

• term är den term som ska definieras, vars definition finns i beskrivningen.
• beskrivning är antingen ett objekt i en punktlista eller numrerad lista eller definitionen av en term.

Exempel:

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>

Den här taggen används i andra taggar, till exempel <summary> (§D.3.16) eller <returns> (§D.3.13), och tillåter att struktur läggs till i text.

Syntax:

<para>innehåll</para>

där

• innehållet är texten i stycket.

Exempel:

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>

Den här taggen används för att beskriva en parameter för en metod, konstruktor eller indexerare.

Syntax:

<param name="namnbeskrivning"></param>

där

• name är namnet på parametern.
• beskrivning är en beskrivning av parametern.

Exempel:

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>

Den här taggen används för att indikera att ett ord är en parameter. Dokumentationsfilen kan bearbetas för att formatera den här parametern på något distinkt sätt.

Syntax:

<paramref name="Namn"/>

där

• name är namnet på parametern.

Exempel:

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-behörighet <>

Med den här taggen kan säkerhetstillgängligheten för en medlem dokumenteras.

Syntax:

<permission cref="medlemsbeskrivning"></permission>

där

• medlem är namnet på en medlem. Dokumentationsgeneratorn kontrollerar att det angivna kodelementet finns och översätter medlemmen till det kanoniska elementnamnet i dokumentationsfilen.
• beskrivning är en beskrivning av åtkomsten till medlemmen.

Exempel:

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

D.3.12 <kommentarer>

Den här taggen används för att ange extra information om en typ. Använd <summary> (§D.3.16) för att beskriva själva typen och medlemmarna av en typ.

Syntax:

<remarks>beskrivning</remarks>

där

• beskrivningen är texten i kommentaren.

Exempel:

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

Den här taggen används för att beskriva returvärdet för en metod.

Syntax:

<returns>beskrivning</returns>

där

• beskrivning är en beskrivning av returvärdet.

Exempel:

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

Med den här taggen kan en länk anges i text. Använd <seealso> (§D.3.15) för att ange text som ska visas i underklienten Se även .

Syntax:

<see cref="nyckelord för medlems-URL" href="" langword="" />

där

• medlem är namnet på en medlem. Dokumentationsgeneratorn kontrollerar att det angivna kodelementet finns och ändrar medlemmen till elementnamnet i den genererade dokumentationsfilen.
• url är en referens till en extern källa.
• langword är ett ord som ska markeras på något sätt.

Exempel:

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>

Med den här taggen kan en post genereras för underklienten Se även . Använd <see> (§D.3.14) för att ange en länk inifrån text.

Syntax:

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

där

• medlem är namnet på en medlem. Dokumentationsgeneratorn kontrollerar att det angivna kodelementet finns och ändrar medlemmen till elementnamnet i den genererade dokumentationsfilen.
• url är en referens till en extern källa.

Exempel:

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

Sammanfattning av D.3.16 <>

Den här taggen kan användas för att beskriva en typ eller en medlem av en typ. Använd <remarks> (§D.3.12) för att ange extra information om typen eller medlemmen.

Syntax:

<summary>beskrivning</summary>

där

• beskrivning är en sammanfattning av typen eller medlemmen.

Exempel:

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>

Den här taggen används för att beskriva en typparameter för en allmän typ eller metod.

Syntax:

<typeparam name="namnbeskrivning"></typeparam>

där

• name är namnet på typparametern.
• beskrivning är en beskrivning av typparametern.

Exempel:

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

D.3.18 <typeparamref>

Den här taggen används för att indikera att ett ord är en typparameter. Dokumentationsfilen kan bearbetas för att formatera den här typparametern på något distinkt sätt.

Syntax:

<typeparamref name="Namn"/>

där

• name är namnet på typparametern.

Exempel:

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-värde <>

Med den här taggen kan en egenskap beskrivas.

Syntax:

<value>egenskapsbeskrivning</value>

där

• egenskapsbeskrivning är en beskrivning av egenskapen.

Exempel:

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

D.4 Bearbeta dokumentationsfilen

D.4.1 Allmänt

Följande information är avsedd för C#-implementeringar som riktar sig till CLI.

Dokumentationsgeneratorn genererar en ID-sträng för varje element i källkoden som är taggad med en dokumentationskommentare. Den här ID-strängen identifierar unikt ett källelement. Ett dokumentationsvisare kan använda en ID-sträng för att identifiera motsvarande objekt som dokumentationen gäller för.

Dokumentationsfilen är inte en hierarkisk representation av källkoden. I stället är det en platt lista med en genererad ID-sträng för varje element.

D.4.2 ID-strängformat

Dokumentationsgeneratorn observerar följande regler när den genererar ID-strängarna:

• Inget tomt utrymme placeras i strängen.

• Den första delen av strängen identifierar vilken typ av medlem som dokumenteras, via ett enda tecken följt av ett kolon. Följande typer av medlemmar definieras:

  Karaktär	Beskrivning
  E	Event
  F	Fält
  M	Metod (inklusive konstruktorer, slutförare och operatorer)
  N	Namnområde
  P	Egenskap (inklusive indexerare)
  T	Typ (till exempel klass, ombud, uppräkning, gränssnitt och struct)
  !	Felsträng; resten av strängen innehåller information om felet. Dokumentationsgeneratorn genererar till exempel felinformation för länkar som inte kan lösas.

• Den andra delen av strängen är det fullständigt kvalificerade namnet på elementet, med början i roten i namnområdet. Namnet på elementet, dess omslutande typ och namnområde avgränsas med punkter. Om namnet på själva objektet har punkter ersätts de med # (U+0023) tecken. (Det antas att inget element har det här tecknet i sitt namn.) Skriv argument i det fullständigt kvalificerade namnet, för när en medlem uttryckligen implementerar en medlem i ett generiskt gränssnitt, kodas genom att ersätta "<" och ">" som omger dem med tecknen "{" och "}".

• För metoder och egenskaper med argument följer argumentlistan, omgiven av parenteser. För dem utan argument utelämnas parenteserna. Argumenten avgränsas med kommatecken. Kodningen för varje argument är densamma som en CLI-signatur enligt följande:

  • Argumenten representeras av deras dokumentationsnamn, som baseras på deras fullständigt kvalificerade namn, som ändras på följande sätt:
    • Argument som representerar generiska typer har ett bifogat "'" tecken följt av antalet typparametrar
    • Argument som inhar modifieraren , out eller ref har följande @ typnamn. Argument som skickas efter värde eller via params har ingen särskild notation.
    • Argument som är matriser representeras som [ lägre storlek : , ... ,lägre trafik : storlek ] där antalet kommatecken är rangordningen mindre en, och de lägre gränserna och storleken på varje dimension, om det är känt, representeras i decimaltal. Om en lägre gräns eller storlek inte har angetts utelämnas den. Om den lägre gränsen och storleken för en viss dimension utelämnas utelämnas även ":". Ojämna matriser representeras av ett "[]" per nivå. Endimensionella matriser utelämnar den nedre gränsen när den nedre gränsen är 0 (standardvärdet) (§17.1).
    • Argument som har andra pekartyper än void representeras med hjälp av följande * typnamn. En void pekare representeras med ett typnamn på System.Void.
    • Argument som refererar till generiska typparametrar som definierats för typer kodas med tecknet "`" följt av det nollbaserade indexet för typparametern.
    • Argument som använder generiska typparametrar som definierats i metoder använder en dubbel-backtick "``" i stället för "`" som används för typer.
    • Argument som refererar till konstruerade generiska typer kodas med den generiska typen följt av "{", följt av en kommaavgränsad lista med typargument följt av "}".

Exempel på D.4.3 ID-sträng

I följande exempel visas ett fragment av C#-kod, tillsammans med ID-strängen som skapas från varje källelement som kan ha en dokumentationskommentare:

Typer representeras med sitt fullständigt kvalificerade namn, utökat med allmän information:

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"

Fält representeras av deras fullständigt kvalificerade namn.

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"

Konstruktörer

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

Slutförare

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

Id:

"M:Acme.Widget.Finalize"

Metoder

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

Egenskaper och indexerare

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

Händelser

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

Id:

"E:Acme.Widget.AnEvent"

Unary-operatorer

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

Id:

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

Den fullständiga uppsättningen unary-operatorns funktionsnamn som används är följande: , , , , op_Incrementop_OnesComplement, op_Decrement, op_Trueoch op_False. op_LogicalNotop_UnaryNegationop_UnaryPlus

Binära operatorer

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

Id:

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

Den fullständiga uppsättningen med binära operatorfunktionsnamn som används är följande: op_Addition, op_Subtraction, op_Multiply, op_Division, op_Modulus, op_BitwiseAnd, op_BitwiseOr, op_ExclusiveOr, op_LeftShift, op_RightShift, op_Inequalityop_Equality, op_LessThan, op_LessThanOrEqual, op_GreaterThanoch op_GreaterThanOrEqual.

Konverteringsoperatorer har ett avslutande "~" följt av returtypen. När antingen källan eller målet för en konverteringsoperator är en allmän typ ersätts tecknen "<" och "">" med tecknen "{" respektive "}".

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

C#-källkod för D.5.1

I följande exempel visas källkoden för en Point-klass:

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

Här är utdata som genereras av en dokumentationsgenerator när du får källkoden för klassen Point, som visas ovan:

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

Slut på informativ text.