D. melléklet Dokumentációs megjegyzések

Ez a melléklet tájékoztató jellegű.

D.1 Általános tudnivalók

A C# mechanizmust biztosít a programozók számára, hogy kódjukat XML szöveget tartalmazó megjegyzésszintaxissal dokumentálják. A forráskódfájlokban egy bizonyos formájú megjegyzések arra használhatók, hogy egy eszközt XML előállítására irányítsanak ezekből a megjegyzésekből és az azokat megelőző forráskód elemekből. Az ilyen szintaxist használó megjegyzéseket dokumentációs megjegyzéseknek nevezzük. Közvetlenül meg kell előzniük egy felhasználó által definiált típust (például osztályt, meghatalmazottat vagy felületet) vagy egy tagot (például mezőt, eseményt, tulajdonságot vagy metódust). Az XML-generáló eszközt dokumentációgenerátornak nevezik. (Ez a generátor maga a C# fordító lehet, de nem kell, hogy az legyen.) A dokumentációs generátor által előállított kimenetet dokumentációs fájlnak nevezzük. A dokumentációs fájl bemenetként szolgál a dokumentáció megjelenítőjéhez; olyan eszköz, amelynek célja a típusinformációk és a kapcsolódó dokumentáció valamiféle vizuális megjelenítése.

A megfelelő C# fordítónak nem kell ellenőriznie a dokumentációs megjegyzések szintaxisát; Az ilyen megjegyzések egyszerűen hétköznapi megjegyzések. A megfelelő fordító azonban elvégezheti az ilyen ellenőrzést.

Ez a specifikáció szabványos címkéket javasol a dokumentációs megjegyzésekben, de ezeknek a címkéknek a használata nem kötelező, és más címkék is használhatók, ha szükséges, mindaddig, amíg a jól formázott XML szabályait betartják. A parancssori felületet célzó C#-implementációk esetében a dokumentációgenerátorról és a dokumentációs fájl formátumáról is tájékoztatást nyújt. A dokumentációs megjelenítőről nem adunk információt.

D.2 Bevezetés

A bizonyos formájú megjegyzések segítségével egy eszköz XML-t állíthat elő ezekből a megjegyzésekből és az azokat megelőző forráskód-elemekből. Az ilyen megjegyzések Single_Line_Comments (6.3.3), amelyek három perjellel (///) kezdődnek, vagy Delimited_Comments (6.3.3), amelyek perjellel és két csillaggal ()/** kezdődnek. Közvetlenül meg kell előzniük egy felhasználó által definiált típust vagy egy jegyzettel ellátott tagot. Az attribútumszakaszok (23.3.§) a deklarációk részét képezik, ezért a dokumentációs megjegyzéseknek meg kell előznie egy típusra vagy tagra alkalmazott attribútumokat.

Magyarázati célból a dokumentum megjegyzéseinek formátuma az alábbiakban két nyelvtani szabályként jelenik meg: Single_Line_Doc_Comment és Delimited_Doc_Comment. Ezek a szabályok azonban nem részei a C# nyelvtanának, hanem a Single_Line_Comment és a Delimited_Comment lexerszabályok adott formátumát képviselik.

Szintaxis:

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

Ha egy Single_Line_Doc_Comment az aktuális Single_Line_Doc_Comment melletti /// karakterei után szóköz karakter található, akkor az a szóköz karakter nem szerepel az XML kimenetben.

Ha egy Delimited_Doc_Comment a második sor első nem szóköz karaktere CSILLAG, és a választható szóköz karakterek és a CSILLAG karakterek ugyanaz a mintája ismétlődik a Delimited_Doc_Comment minden sorának elején, akkor az ismétlődő minta karakterei nem szerepelnek az XML kimenetben. A minta tartalmazhat szóköz karaktereket a CSILLAG karakter után és előtt is.

példa:

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

A dokumentációs megjegyzések szövegének jól formázottnak kell lennie az XML szabályai szerint (http://www.w3.org/TR/REC-xml). Ha az XML rosszul van formázva, figyelmeztetés jelenik meg, és a dokumentációs fájl tartalmaz egy megjegyzést, amely szerint hiba történt.

Bár a fejlesztők szabadon létrehozhatják saját címkekészletüket, az ajánlott készletet a D.3 határozza meg. Néhány ajánlott címke különleges jelentéssel rendelkezik:

A <param> címke a paraméterek leírására szolgál. Ha ilyen címkét használ, a dokumentáció-generátornak ellenőriznie kell, hogy a megadott paraméter létezik-e, és hogy az összes paraméter le van-e írva a dokumentációs megjegyzésekben. Ha az ellenőrzés sikertelen, a dokumentációgenerátor figyelmeztetést ad ki.
Az cref attribútum bármely címkéhez csatolható, hogy egy kódelemre hivatkozzon. A dokumentációgenerátornak ellenőriznie kell, hogy létezik-e ez a kódelem. Ha az ellenőrzés sikertelen, a dokumentációgenerátor figyelmeztetést ad ki. Amikor egy cref attribútumban leírt nevet keres, a dokumentáció-generátornak tiszteletben kell tartania a névtér láthatóságát a forráskódban megjelenő utasítások használata szerint. Az általános kódelemek esetében a normál általános szintaxis (pl. "List<T>") nem használható, mert érvénytelen XML-t hoz létre. Zárójelek helyett kapcsos zárójelek használhatók (pl.; "List{T}"), vagy az XML escape szintaxisa használható (pl. "List<T>").
A <summary> címkét a dokumentáció megjelenítője használja a típussal vagy taggal kapcsolatos további információk megjelenítésére.
A <include> címke egy külső XML-fájlból származó információkat tartalmaz.

Figyelje meg, hogy a dokumentációs fájl nem tartalmaz teljes információt a típusról és a tagokról (például nem tartalmaz típusadatokat). Ahhoz, hogy ilyen információkat kapjunk egy típusról vagy tagról, a dokumentációs fájlt a típusra vagy tagra vonatkozó reflexióval együtt kell használni.

Egy részleges típus vagy egy részleges metódus több részben deklarálható, amelyek mindegyike lehet egy vagy több fordítási egységben, és amelyek mindegyike egy vagy több dokumentációs megjegyzést tartalmazhat. A részleges metódusnak általában van egy "részleges deklarációja" és egy "részleges deklarációja".

Részleges típus esetén az adott típusra közvetlenül vonatkozó dokumentummegjegyzések (ha vannak ilyenek) az egyes részekből mind meghatározatlan sorrendben kerülnek a dokumentációs fájlba.

Részleges módszer esetén:

Ha egy meghatározó részleges nyilatkozat nem rendelkezik megfelelő végrehajtási részleges deklarációval, a meghatározó részleges nyilatkozatban szereplő dokumentációs megjegyzéseket figyelmen kívül hagyja (mivel a nyilatkozat törlődik).
Ellenkező esetben, ha a végrehajtási részleges nyilatkozat dokumentációs megjegyzéseket tartalmaz, azokat a dokumentációs fájlba írja, és a meghatározó részleges nyilatkozatban szereplő dokumentációs megjegyzéseket figyelmen kívül hagyja.
Ellenkező esetben a meghatározó részleges nyilatkozatban szereplő dokumentációs megjegyzések a dokumentációs fájlba kerülnek.

D.3 Ajánlott címkék

D.3.1 Általános tudnivalók

A dokumentáció-generátornak el kell fogadnia és fel kell dolgoznia minden olyan címkét, amely az XML szabályai szerint érvényes. A következő címkék a felhasználói dokumentációban gyakran használt funkciókat tartalmazzák. (Természetesen más címkék is lehetségesek.)

Címke	Utalás	Cél
`<c>`	§D.3.2	Szöveg beállítása kódszerű betűtípussal
`<code>`	D.3.3.	Állítson be egy vagy több sor forráskódot vagy programkimenetet
`<example>`	§D.3.4	Jelöljön meg egy példát
`<exception>`	D.3.5.	Azonosítja a metódus által okozott kivételeket
`<include>`	D.3.6.	XML-t tartalmaz egy külső fájlból
`<list>`	§D.3.7	Lista vagy tábla létrehozása
`<para>`	D.3.8.	Szerkezet szöveghez való hozzáadásának engedélyezése
`<param>`	D.3.9.	Metódus vagy konstruktor paraméterének leírása
`<paramref>`	D.3.10.	Annak azonosítása, hogy egy szó paraméternév-e
`<permission>`	§D.3.11	Tagok biztonsági akadálymentesítésének dokumentálása
`<remarks>`	§D.3.12	Leírás a típusról
`<returns>`	§D.3.13	Metódus visszatérési értékének leírása
`<see>`	D.3.14.	Hivatkozás megadása
`<seealso>`	D.3.15. szakasz	Lásd még bejegyzés létrehozása
`<summary>`	D.3.16. szakasz	Típus vagy típus tagjának leírása
`<typeparam>`	D.3.17.	Általános típus vagy metódus típusparaméterének leírása
`<typeparamref>`	D.3.18. szakasz	Annak azonosítása, hogy egy szó típusparaméter-név
`<value>`	D.3.19. szakasz	Tulajdonság leírása

D.3.2 <c>

Ez a címke egy olyan mechanizmust biztosít, amely jelzi, hogy a leíráson belüli szövegtöredéket speciális betűtípussal kell beállítani, például egy kódblokkhoz. A tényleges kód sorainál a (<code>) pontot kell használni .

Szintaxis:

<c> SMS</c>

példa:

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

D.3.3 <. kód>

Ez a címke egy vagy több sor forráskód vagy programkimenet beállítására szolgál valamilyen speciális betűtípussal. A narratívában szereplő kis kódtöredékek esetében használja a (<c>) parancsot .

Szintaxis:

<code> forráskód vagy program kimenete</code>

példa:

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 <példa>

Ez a címke lehetővé teszi a megjegyzésen belüli példakód használatát, hogy megadja, hogyan lehet használni egy metódust vagy más könyvtártagot. Általában ez magában foglalja a címke <code> használatát is (§D.3.3).

Szintaxis:

<example> leírás</example>

példa:

Lásd <code> a (§D.3.3) példát.

D.3.5 <kivétel>

Ez a címke lehetővé teszi a metódus által okozott kivételek dokumentálását.

Szintaxis:

<exception cref=" tag">leírás</exception>

ebben:

cref=" tag" egy tag neve. A dokumentációgenerátor ellenőrzi, hogy az adott tag létezik-e, és lefordítja a tagot a dokumentációs fájlban szereplő kanonikus elem nevére.
A leírás azoknak a körülményeknek a leírása, amelyek között a kivétel megtörténik.

példa:

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

Ez a címke lehetővé teszi a forráskódfájlon kívüli XML-dokumentumokból származó információk felvételét. A külső fájlnak jól formázott XML-dokumentumnak kell lennie, és a dokumentumra egy XPath-kifejezést alkalmaz annak meghatározására, hogy a dokumentumból milyen XML-t kell tartalmaznia. A <include> címke ezután lecserélődik a külső dokumentumból kiválasztott XML-re.

Szintaxis:

<include file=" fájlnév" path="xpath" />

ebben:

file=" fájlnév" egy külső XML-fájl fájlneve. A fájlnevet a belefoglalási címkét tartalmazó fájlhoz viszonyítva értelmezi a rendszer.
path=" xpath" egy XPath-kifejezés, amely kijelöli az XML egy részét a külső XML-fájlban.

Példa:

Ha a forráskód tartalmaz egy olyan deklarációt, mint:

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

és a "docs.xml" külső fájl a következő tartalmat tartalmazta:

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

akkor ugyanaz a dokumentáció jelenik meg, mintha a forráskód tartalmazná:

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

D.3.7 <lista>

Ez a címke elemlista vagy -táblázat létrehozására szolgál. Tartalmazhat egy blokkot <listheader> egy tábla vagy definíciós lista címsorának meghatározásához. (Táblázat definiálásakor csak a címsorban szereplő kifejezés bejegyzését kell megadni.)

A lista minden eleme blokkkal <item> van megadva. Definíciós lista létrehozásakor a kifejezést és a leírást is meg kell adni. Táblázat, listajeles lista vagy számozott lista esetén azonban csak a leírást kell megadni.

Szintaxis:

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

ebben:

kifejezés a meghatározandó kifejezés, amelynek meghatározása a leírásban található.
A leírás egy listajel vagy számozott lista eleme, vagy egy kifejezés definíciója.

példa:

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 <. bekezdés>

Ez a címke más címkékben használható, mint például <summary> a (§D.3.16) vagy a <returns> (.§D.3.13), és lehetővé teszi a struktúra hozzáadását a szöveghez.

Szintaxis:

<para> tartalom</para>

ebben:

A tartalom a bekezdés szövege.

példa:

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

Ez a címke egy metódus, konstruktor vagy indexelő paraméterének leírására szolgál.

Szintaxis:

<param name=" név">leírás</param>

ebben:

name a paraméter neve.
A leírás a paraméter leírása.

példa:

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 <paraméter>

Ez a címke azt jelzi, hogy egy szó paraméter. A dokumentációs fájl feldolgozható a paraméter valamilyen eltérő módon történő formázására.

Szintaxis:

<paramref name=" név"/>

ebben:

name a paraméter neve.

példa:

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 <engedély>

Ez a címke lehetővé teszi a tag biztonsági hozzáférhetőségének dokumentálását.

Szintaxis:

<permission cref=" tag">leírás</permission>

ebben:

tag a tag neve. A dokumentációgenerátor ellenőrzi, hogy az adott kódelem létezik-e, és lefordítja a tagot a dokumentációs fájlban szereplő kanonikus elem nevére.
A leírás a taghoz való hozzáférés leírása.

példa:

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

D.3.12 <megjegyzések>

Ez a címke a típussal kapcsolatos további információk megadására szolgál. Használja <summary> a (D.3.16) pontot magának a típusnak és a típus tagjainak leírására.

Szintaxis:

<remarks> leírás</remarks>

ebben:

leírás a megjegyzés szövege.

példa:

/// <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 <Visszaküldések>

Ez a címke egy metódus visszatérési értékének leírására szolgál.

Szintaxis:

<returns> leírás</returns>

ebben:

A leírás a visszatérési érték leírása.

példa:

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 <. lásd>

Ez a címke lehetővé teszi a hivatkozás szövegen belüli megadását. A (<seealso>) jellel jelezheti a Lásd még almondatban megjelenő szöveget.

Szintaxis:

<see cref=" tag" href="URL-cím" langword="kulcsszó" />

ebben:

tag a tag neve. A dokumentációgenerátor ellenőrzi, hogy az adott kódelem létezik-e, és megváltoztatja a tagot az elem nevére a generált dokumentációs fájlban.
Az URL egy külső forrásra mutató hivatkozás.
A langword egy olyan szó, amelyet valahogy ki kell emelni.

példa:

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 <lásd még>

Ez a címke lehetővé teszi a Lásd még alzáradékhoz tartozó bejegyzés létrehozását. A (<see>) paranccsal adjon meg egy hivatkozást a szövegen belül.

Szintaxis:

<seealso cref=" tag" href="URL-cím" />

ebben:

tag a tag neve. A dokumentációgenerátor ellenőrzi, hogy az adott kódelem létezik-e, és megváltoztatja a tagot az elem nevére a generált dokumentációs fájlban.
Az URL egy külső forrásra mutató hivatkozás.

példa:

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

D.3.16 <összefoglalás>

Ez a címke egy típus vagy egy típus tagjának leírására használható. A (<remarks>) paranccsal adjon meg további információkat a típusról vagy a tagról.

Szintaxis:

<summary> leírás</summary>

ebben:

A leírás a típus vagy tag összegzése.

példa:

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 <típusparaméter>

Ez a címke egy általános típus vagy metódus típusparaméterének leírására szolgál.

Szintaxis:

<typeparam name=" név">leírás</typeparam>

ebben:

name a type paraméter neve.
A leírás a type paraméter leírása.

példa:

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

D.3.18 <típusparaméter>

Ez a címke azt jelzi, hogy egy szó típusparaméter. A dokumentációs fájl feldolgozható a típusparaméter valamilyen különböző módon történő formázásához.

Szintaxis:

<typeparamref name=" név"/>

ebben:

name a type paraméter neve.

példa:

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 <érték>

Ez a címke lehetővé teszi egy tulajdonság leírását.

Szintaxis:

<value> Ingatlan leírása</value>

ebben:

A tulajdonság leírása az ingatlan leírása.

példa:

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

D.4 A dokumentációs fájl feldolgozása

D.4.1 Általános tudnivalók

Az alábbi információk a parancssori felületet célzó C#-implementációkra vonatkoznak.

A dokumentációgenerátor létrehoz egy azonosító karakterláncot a forráskód minden olyan eleméhez, amely dokumentációs megjegyzéssel van megjelölve. Ez az azonosító sztring egyedileg azonosítja a forráselemet. A dokumentációmegjelenítő azonosító sztring segítségével azonosíthatja a megfelelő elemet, amelyre a dokumentáció vonatkozik.

A dokumentációs fájl nem a forráskód hierarchikus ábrázolása; inkább egy lapos lista, amely minden elemhez generált azonosító karakterláncot tartalmaz.

D.4.2 azonosító karakterlánc formátum

A dokumentációgenerátor a következő szabályokat veszi figyelembe az azonosító sztringek létrehozásakor:

A sztringben nincs szabad terület.

A karakterlánc első része azonosítja a dokumentált tag típusát egyetlen karakterrel, amelyet kettőspont követ. A következő típusú tagok vannak definiálva:

Karakter	Leírás
E	Esemény
F	szakterület
M	Metódus (beleértve a konstruktorokat, véglegesítőket és operátorokat)
N	Namespace
P	Tulajdonság (beleértve az indexelőket is)
T	Típus (például osztály, delegálás, felsorolás, felület és struktúra)
!	Hibaszöveg; A sztring többi része a hibával kapcsolatos információkat tartalmaz. A dokumentációgenerátor például hibainformációkat generál a nem feloldható hivatkozásokhoz.

A karakterlánc második része az elem teljes neve, a névtér gyökerétől kezdve. Az elem nevét, a beágyazó típusokat és a névteret pontok választják el egymástól. Ha magának az elemnek a neve pontokkal rendelkezik, akkor azokat # (U+0023) karakterek helyettesítik. (Feltételezzük, hogy egyetlen elem nevében sincs ilyen karakter.) A teljes név argumentumait úgy kódolják, hogy az őket körülvevő "<" és ">" karaktereket a "{" és a "}" karakterekkel helyettesítik.
Az argumentumokat tartalmazó metódusok és tulajdonságok esetében az argumentumlista következik, zárójelben. Azoknál, akiknek nincs érve, a zárójelek kimaradnak. Az argumentumokat vesszők választják el egymástól. Az egyes argumentumok kódolása megegyezik a CLI-aláírással, az alábbiak szerint:
- Az argumentumokat a dokumentációs nevük képviseli, amely a teljes nevükön alapul, az alábbiak szerint módosítva:
  - Az általános típusokat képviselő argumentumokhoz egy "'" karakter fűződik, amelyet a típusparaméterek száma követ
  - A , in vagy módosító outref argumentumok @típusneve a következő. Az érték vagy a via params által átadott argumentumoknak nincs speciális jelölése.
  - A tömböket tartalmazó argumentumok [:, vannak ábrázolva ... , alsó határ:méret] ahol a vesszők száma az eggyel kisebb rang, és az egyes dimenziók alsó határai és méretei, ha ismertek, tizedesjegyben vannak ábrázolva. Ha nincs megadva alsó határ vagy méret, az kimarad. Ha egy adott dimenzió alsó határa és mérete nincs megadva, a ":" is kimarad. A szaggatott tömböket szintenként egy "[]" jelöli. Az egydimenziós tömbök kihagyják az alsó határt, ha az alsó határ 0 (alapértelmezett) (17.1).
  - A mutatótípustól void eltérő argumentumokat a * típus neve követi. A void mutatót a típusnév jelképezi.System.Void
  - A típusokon definiált általános típusparaméterekre hivatkozó argumentumok kódolása a "`" karakterrel, amelyet a típusparaméter nulla alapú indexe követ.
  - A metódusokban definiált általános típusparamétereket használó argumentumok dupla backtick "``" értéket használnak a típusokhoz használt "`" helyett.
  - A konstruált általános típusokra hivatkozó argumentumok az általános típussal vannak kódolva, amelyet a "{" követ, majd a típusargumentumok vesszővel tagolt listája, majd a "".}

D.4.3 Példák azonosító karakterláncokra

Az alábbi példák mindegyike a C#-kód egy töredékét mutatja be, valamint az egyes forráselemekből előállított azonosító sztringet, amely dokumentációs megjegyzéssel rendelkezik:

A típusokat a teljes nevükkel ábrázoljuk, általános információkkal kiegészítve:

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

Azonosítók:

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

A mezőket a teljes név jelöli.

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

Azonosítók:

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

Konstruktorok

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

Azonosítók:

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

Döntősök

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

Azonosítók:

"M:Acme.Widget.Finalize"

Módszerek

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

Azonosítók:

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

Tulajdonságok és indexelők

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

Azonosítók:

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

Események

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

Azonosítók:

"E:Acme.Widget.AnEvent"

Unáris operátorok

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

Azonosítók:

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

Az unáris operátor függvénynevek teljes készlete a következő: op_UnaryPlus, op_UnaryNegation, op_LogicalNot, op_OnesComplement, op_Increment, op_Decrement, , op_Trueés op_False.

Bináris operátorok

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

Azonosítók:

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

A bináris operátor függvénynevek teljes készlete a következő: op_Addition, , op_Subtractionop_Multiplyop_Divisionop_Modulusop_BitwiseAndop_BitwiseOrop_ExclusiveOrop_LeftShiftop_RightShiftop_Equalityop_Inequalityop_LessThanop_LessThanOrEqualop_GreaterThanop_GreaterThanOrEqual

A konverziós operátorok záró "~" betűvel rendelkeznek, amelyet a visszatérési típus követ. Ha a konverziós operátor forrása vagy célhelye általános típusú, akkor a "<" és a "">" karaktereket a "{" és a "}" karakterek váltják fel.

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

Azonosítók:

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

D.5 Példa

D.5.1 C# forráskód

Az alábbi példa egy Point osztály forráskódját mutatja be:

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 Eredményül kapott XML

Íme az egyik dokumentációs generátor által előállított kimenet, amikor megkapja a fent látható osztály Pointforráskódját:

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

Az informatív szöveg vége.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-09-12

Megosztás a következőn keresztül:

D. melléklet Dokumentációs megjegyzések

D.1 Általános tudnivalók

D.2 Bevezetés

D.3 Ajánlott címkék

D.3.1 Általános tudnivalók

D.3.2 <c>

D.3.3 <. kód>

D.3.4 <példa>

D.3.5 <kivétel>

D.3.6 <.>

D.3.7 <lista>

D.3.8 <. bekezdés>

D.3.9 <paraméter>

D.3.10 <paraméter>

D.3.11 <engedély>

D.3.12 <megjegyzések>

D.3.13 <Visszaküldések>

D.3.14 <. lásd>

D.3.15 <lásd még>

D.3.16 <összefoglalás>

D.3.17 <típusparaméter>

D.3.18 <típusparaméter>

D.3.19 <érték>

D.4 A dokumentációs fájl feldolgozása

D.4.1 Általános tudnivalók

D.4.2 azonosító karakterlánc formátum

D.4.3 Példák azonosító karakterláncokra

D.5 Példa

D.5.1 C# forráskód

D.5.2 Eredményül kapott XML

Visszajelzés

További források