XML API dokumentációs megjegyzések létrehozása

A C#-forrásfájlok olyan strukturált megjegyzéseket tartalmazhatnak, amelyek API-dokumentációt készítenek az ezekben a fájlokban meghatározott típusokhoz. A C#-fordító létrehoz egy XML-fájlt , amely strukturált adatokat tartalmaz a megjegyzések és az API-aláírások megjelenítéséhez. Más eszközök feldolgozhatják ezt az XML-kimenetet, hogy például weblapok vagy PDF-fájlok formájában emberi olvasásra alkalmas dokumentációt hozzanak létre.

Ez a folyamat számos előnnyel jár, ha API-dokumentációt ad hozzá a kódhoz:

A C#-fordító egyetlen XML-dokumentumba egyesíti a C#-kód szerkezetét a megjegyzések szövegével.
A C#-fordító ellenőrzi, hogy a megjegyzések megfelelnek-e a vonatkozó címkék API-aláírásainak.
Az XML-dokumentációs fájlokat feldolgozó eszközök meghatározhatják az adott eszközökre jellemző XML-elemeket és attribútumokat.

Az olyan eszközök, mint a Visual Studio, számos gyakori XML-elemhez biztosítják az IntelliSense-t a dokumentáció megjegyzéseiben.

Ez a cikk az alábbi témaköröket ismerteti:

Dokumentációs megjegyzések és XML-fájlok létrehozása
A C#-fordító és a Visual Studio által ellenőrzött címkék
A létrehozott XML-fájl formátuma

XML-dokumentáció kimenetének létrehozása

A kód dokumentációját úgy hozhatja létre, hogy három perjellel jelölt speciális megjegyzésmezőket ír. A megjegyzésmezők olyan XML-elemeket tartalmaznak, amelyek a megjegyzéseket követő kódblokkot írják le. Például:

/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass { }

Beállíthatja a GenerateDocumentationFile vagy a DocumentationFile beállítást, és a fordító megkeresi a forráskódban XML-címkékkel rendelkező összes megjegyzésmezőt, és létrehoz egy XML-dokumentációs fájlt ezekből a megjegyzésekből. Ha ez a beállítás engedélyezve van, a fordító létrehozza a CS1591 figyelmeztetést a projektben xml dokumentáció megjegyzései nélkül deklarált bármely nyilvánosan látható tagra vonatkozóan.

XML-megjegyzésformátumok

Az XML-dokumentum megjegyzéseinek használatához elválasztójelek szükségesek, amelyek jelzik, hogy hol kezdődik és végződik egy dokumentációs megjegyzés. A következő elválasztójeleket használja az XML-dokumentáció címkéivel:

/// Egysoros elválasztó: A dokumentációs példák és a C# projektsablonok ezt az űrlapot használják. Ha a térköz az elválasztójelet követi, az nem szerepel az XML-kimenetben.

Megjegyzés:

A Visual Studio automatikusan beszúrja és elhelyezi a <summary></summary> kurzort ezekben a címkékben, miután beírta a /// elválasztójelet a kódszerkesztőbe. Ezt a funkciót be- és kikapcsolhatja a Beállítások párbeszédpanelen.
/** */ Többsoros elválasztójelek: A /** */ határolójelek a következő formázási szabályokkal rendelkeznek:
- Ha a /** vonal többi része üres terület, akkor a vonal nem lesz feldolgozva megjegyzésekhez. Ha a /** határolójel utáni első karakter a fehér terület, a rendszer figyelmen kívül hagyja a fehér szóköz karaktert, és a sor többi részét feldolgozzák. Ellenkező esetben a határolót követő /** sor teljes szövege a megjegyzés részeként lesz feldolgozva.
- A határolóvonalat tartalmazó */ vonalon, ha csak fehér terület van a határolóig, a */ vonal figyelmen kívül lesz hagyva. Ellenkező esetben a */ szöveg a határoló sorában a megjegyzés részeként lesz feldolgozva.
- A határolóval /** kezdődő sorok esetében a fordító az egyes sorok elején egy közös mintát keres. A minta lehet választható fehér szóköz és/vagy csillag (*), amelyet további választható fehér szóköz követ. Ha a fordító minden sor elején talál egy közös mintát, amely nem a /** határolóval kezdődik, vagy az elválasztóval végződik, figyelmen kívül hagyja ezt a */ mintát az egyes sorokhoz.
- A következő feldolgozott megjegyzés egyetlen része az a sor, amely a következővel <summary>kezdődik: A három címkeformátum ugyanazokat a megjegyzéseket hozza létre.
```
/** <summary>text</summary> */

/**
<summary>text</summary>
*/

/**
* <summary>text</summary>
*/
```
- A fordító a második és a harmadik sor elején azonosítja a " * " gyakori mintáját. A minta nem szerepel a kimenetben.
```
/**
* <summary>
* text </summary>*/
```
- A fordító nem talál gyakori mintát a következő megjegyzésben, mert a harmadik sor második karaktere nem csillag. A második és a harmadik sor összes szövege a megjegyzés részeként lesz feldolgozva.
```
/**
* <summary>
   text </summary>
*/
```
- A fordító két okból nem talál mintát az alábbi megjegyzésben. Először is, a csillag előtti szóközök száma nem konzisztens. Másodszor, az ötödik sor egy tabulátorsal kezdődik, amely nem egyezik a szóközökkel. A második és az öt sor közötti összes szöveg feldolgozása a megjegyzés részeként történik.
```
/**
  * <summary>
  * text
*  text2
 	*  </summary>
*/
```

Ha XML-elemekre szeretne hivatkozni (például a függvény egy XML-dokumentáció megjegyzésében leírandó xml-elemeket dolgoz fel), használhatja a szabványos idéző mechanizmust (< és >). Ha általános azonosítókra szeretne hivatkozni a kódhivatkozási (cref) elemekben, használhatja a feloldó karaktereket (például cref="List<T>") vagy a zárójeleket (cref="List{T}"). Különleges eset, hogy a fordító szögletes zárójelként elemzi a zárójeleket, hogy a dokumentáció megjegyzése kevésbé nehézkes legyen a szerző számára az általános azonosítókra való hivatkozáskor.

Megjegyzés:

Ha megjegyzéseket ír az egysoros XML-megjegyzéshatárolóval, ///de nem tartalmaz címkéket, a fordító hozzáadja a megjegyzések szövegét az XML kimeneti fájlhoz. A kimenet azonban nem tartalmaz XML-elemeket, például <summary>. Az XML-megjegyzéseket használó legtöbb eszköz (beleértve a Visual Studio IntelliSense-t is) nem olvassa el ezeket a megjegyzéseket.

Xml-dokumentáció bemenetét elfogadó eszközök

Az alábbi eszközök XML-megjegyzésekből hoznak létre kimenetet:

DocFX: A DocFX a .NET API-dokumentációkészítője, amely jelenleg a C#, a Visual Basic és az F# használatát támogatja. Lehetővé teszi a létrehozott referenciadokumentáció testreszabását is. A DocFX statikus HTML-webhelyet hoz létre a forráskódból és a Markdown-fájlokból. A DocFX emellett rugalmasan testre szabhatja webhelye elrendezését és stílusát sablonokkal. Egyéni sablonokat is létrehozhat.
Sandcastle: A Sandcastle-eszközök segédfájlokat hoznak létre a felügyelt osztálykódtárakhoz, amelyek mind elméleti, mind API-referenciaoldalakat tartalmaznak. A Sandcastle-eszközök parancssori alapúak, és nem rendelkeznek grafikus felhasználói felülettel, projektfelügyeleti funkciókkal vagy automatizált buildelési folyamatokkal. A Sandcastle súgófájl-készítője önálló grafikus felhasználói felületet és parancssori eszközöket biztosít a súgófájl automatizált módon történő létrehozásához. Egy Visual Studio-integrációs csomag is elérhető hozzá, hogy a projekteket teljes egészében a Visual Studióból lehessen létrehozni és felügyelni.
Doxygen: A Doxygen létrehoz egy online dokumentációs böngészőt (HTML-ben) vagy egy offline referencia-kézikönyvet (LaTeX-ben) dokumentált forrásfájlok készletéből. Az RTF (MS Word), a PostScript, a hivatkozásos PDF, a tömörített HTML, a DocBook és a Unix manuális oldalakon is támogatott a kimenet létrehozása. A Doxygen konfigurálható úgy, hogy kinyerje a kódstruktúrát a nem dokumentált forrásfájlokból.

Megjegyzés:

Az XML-dokumentáció megjegyzései nem metaadatok; ezek nem szerepelnek a lefordított szerelvényben, ezért nem érhetők el tükröződés útján.

Azonosító sztringek

A rendszer minden típust vagy tagot a kimeneti XML-fájl egy elemében tárol. Mindegyik elem egyedi azonosító sztringgel rendelkezik, amely azonosítja a típust vagy tagot. Az azonosító sztringnek figyelembe kell vennie az operátorokat, paramétereket, visszatérési értékeket, általános típusparamétereket, refés inout paramétereket. Az összes lehetséges elem kódolásához a fordító egyértelműen meghatározott szabályokat követ az azonosító sztringek létrehozásához. Az XML-fájlt feldolgozó programok az azonosító sztring használatával azonosítják a dokumentáció által érintett .NET-metaadatokat vagy tükröződési elemet.

A fordító a következő szabályokat követi az azonosító sztringek létrehozásakor:

A sztringben nincs szabad terület.

A sztring első része egyetlen karakterrel, majd kettősponttal azonosítja a tagtípust. A rendszer a következő tagtípusokat használja:

Karakter	Tagtípus	Jegyzetek
`N`	névtér	Nem adhat hozzá dokumentációs megjegyzéseket egy névtérhez, de hivatkozhat `cref` rájuk, ahol támogatott.
`T`	típus	A típus egy osztály, interfész, struct, enum vagy delegált.
`F`	mező
`P`	tulajdonság	Indexelőket vagy más indexelt tulajdonságokat is tartalmaz.
`M`	metódus	Speciális módszereket, például konstruktorokat és operátorokat tartalmaz.
`E`	esemény
`!`	hibaszöveg	A sztring többi része információt nyújt a hibáról. A C#-fordító hibainformációkat hoz létre a nem feloldható hivatkozásokhoz.

A sztring második része az elem teljes neve, a névtér gyökerétől kezdve. Az elem neve, a hozzá tartozó típus(ok) és a névtér pontokkal vannak elválasztva. Ha magának az elemnek a neve pontokkal rendelkezik, azokat a rendszer a kivonatjelre ('#' ) cseréli. A nyelvhelyesség azt feltételezi, hogy egyetlen elem sem rendelkezik közvetlenül a nevében kivonat-jellel. A Sztring konstruktor teljes neve például a "System.String.#ctor".
Tulajdonságok és metódusok esetén a zárójelek közé foglalt paraméterlista a következő. Ha nincsenek paraméterek, nincsenek zárójelek. A paramétereket vesszők választják el egymástól. Az egyes paraméterek kódolása közvetlenül követi a .NET-aláírás kódolását (lásd Microsoft.VisualStudio.CorDebugInterop.CorElementType a következő lista összes caps-elemének definícióit):
- Alaptípusok. A normál típusok (ELEMENT_TYPE_CLASS vagy ELEMENT_TYPE_VALUETYPE) a típus teljes neveként jelennek meg.
- A belső típusok (például ELEMENT_TYPE_I4, , ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREFés ELEMENT_TYPE_VOID) a megfelelő teljes típus teljes neveként jelennek meg. Például, System.Int32 vagy System.TypedReference.
- ELEMENT_TYPE_PTR a módosított típust követve "*"-ként jelenik meg.
- ELEMENT_TYPE_BYREF a módosított típust követő "@" karakter jelenik meg.
- ELEMENT_TYPE_CMOD_OPT a módosított típust követve a módosító osztály teljes neve "!" néven jelenik meg.
- ELEMENT_TYPE_SZARRAY a tömb elemtípusát követő "[]" karakter jelenik meg.
- ELEMENT_TYPE_ARRAY [alsó határ:size,alsó határ:size] értékként jelenik meg, ahol a vesszők száma a rang – 1, és az egyes dimenziók alsó határa és mérete, ha ismert, decimális értékben jelenik meg. Ha nincsenek megadva, a rendszer kihagyja az alsó határt és a méretet. Ha egy adott dimenzió alsó határa és mérete nincs megadva, akkor a ":" is ki van hagyva. Például egy kétdimenziós tömb, amelynek alsó határa az 1, a meg nem határozott méretek pedig [1:,1:].
Csak konverziós operátorok esetén (op_Implicit és op_Explicit) a metódus visszatérési értékét a rendszer a visszatérési típus szerint kódolja ~ . Például: <member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32"> az osztályban System.Decimal deklarált öntött operátor public static explicit operator int (decimal value); címkéje.
Általános típusok esetén a típus nevét egy backtick, majd egy szám követi, amely az általános típusparaméterek számát jelzi. Például: egy olyan típus címkéje, amely a következőként public class SampleClass<T, U>van definiálva: <member name="T:SampleClass`2"> . Az általános típusokat paraméterként használó metódusok esetében az általános típusparaméterek a háttérrendszerrel előtaggal ellátott számokként vannak megadva (például "0"1). Minden szám a típus általános paramétereinek nulla alapú tömbjegyzetét jelöli.
- ELEMENT_TYPE_PINNED a módosított típust követve ^-ként jelenik meg. A C#-fordító soha nem hozza létre ezt a kódolást.
- ELEMENT_TYPE_CMOD_REQ a módosított típust követve a módosító osztály teljes neve |ként jelenik meg. A C#-fordító soha nem hozza létre ezt a kódolást.
- ELEMENT_TYPE_GENERICARRAY a tömb elemtípusát követve "[?]" érték jelenik meg. A C#-fordító soha nem hozza létre ezt a kódolást.
- ELEMENT_TYPE_FNPTR az "=FUNC:type(signature)" érték jelenik meg, ahol type a visszatérési típus, az aláírás pedig a metódus argumentuma. Ha nincsenek argumentumok, a zárójelek nem lesznek megadva. A C#-fordító soha nem hozza létre ezt a kódolást.
- A következő aláírási összetevők nem jelennek meg, mert nem használják őket a túlterhelt metódusok megkülönböztetésére:
  - hívási konvenció
  - visszatérési típus
  - ELEMENT_TYPE_SENTINEL

Az alábbi példák bemutatják, hogyan jönnek létre egy osztály és annak tagjai azonosító sztringjei:

namespace MyNamespace;

/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:MyNamespace.MyClass".
/// </summary>
public unsafe class MyClass
{
    /// <summary>
    /// Enter description here for the first constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor".
    /// </summary>
    public MyClass() { }

    /// <summary>
    /// Enter description here for the second constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public MyClass(int i) { }

    /// <summary>
    /// Enter description here for field Message.
    /// ID string generated is "F:MyNamespace.MyClass.Message".
    /// </summary>
    public string? Message;

    /// <summary>
    /// Enter description for constant PI.
    /// ID string generated is "F:MyNamespace.MyClass.PI".
    /// </summary>
    public const double PI = 3.14;

    /// <summary>
    /// Enter description for method Func.
    /// ID string generated is "M:MyNamespace.MyClass.Func".
    /// </summary>
    /// <returns>Describe return value.</returns>
    public int Func() => 1;

    /// <summary>
    /// Enter description for method SomeMethod.
    /// ID string generated is "M:MyNamespace.MyClass.SomeMethod(System.String,System.Int32@,System.Void*)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <param name="num">Describe parameter.</param>
    /// <param name="ptr">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int SomeMethod(string str, ref int num, void* ptr) { return 1; }

    /// <summary>
    /// Enter description for method AnotherMethod.
    /// ID string generated is "M:MyNamespace.MyClass.AnotherMethod(System.Int16[],System.Int32[0:,0:])".
    /// </summary>
    /// <param name="array1">Describe parameter.</param>
    /// <param name="array">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int AnotherMethod(short[] array1, int[,] array) { return 0; }

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)".
    /// </summary>
    /// <param name="first">Describe parameter.</param>
    /// <param name="second">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static MyClass operator +(MyClass first, MyClass second) { return first; }

    /// <summary>
    /// Enter description for property.
    /// ID string generated is "P:MyNamespace.MyClass.Prop".
    /// </summary>
    public int Prop { get { return 1; } set { } }

    /// <summary>
    /// Enter description for event.
    /// ID string generated is "E:MyNamespace.MyClass.OnHappened".
    /// </summary>
    public event Del? OnHappened;

    /// <summary>
    /// Enter description for index.
    /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <returns></returns>
    public int this[string s] => 1;

    /// <summary>
    /// Enter description for class Nested.
    /// ID string generated is "T:MyNamespace.MyClass.Nested".
    /// </summary>
    public class Nested { }

    /// <summary>
    /// Enter description for delegate.
    /// ID string generated is "T:MyNamespace.MyClass.Del".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public delegate void Del(int i);

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32".
    /// </summary>
    /// <param name="myParameter">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static explicit operator int(MyClass myParameter) => 1;
}

C# nyelvspecifikáció

További információkért tekintse meg a C# nyelvi specifikációjának dokumentációs megjegyzésekkel kapcsolatos mellékletét.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-07-31