Ajánlott XML-címkék c# dokumentációs megjegyzésekhez

A C#-dokumentáció megjegyzései XML-elemeket használnak a kimeneti dokumentáció szerkezetének meghatározásához. Ennek a funkciónak az egyik következménye, hogy bármilyen érvényes XML-t hozzáadhat a dokumentáció megjegyzéseihez. A C#-fordító ezeket az elemeket a kimeneti XML-fájlba másolja. Bár bármilyen érvényes XML-t használhat megjegyzéseiben (beleértve az érvényes HTML-elemet is), a kód dokumentálása számos okból javasolt.

Az alábbiakban néhány javaslatot, általános használati esetet és az XML-dokumentáció címkéinek C#-kódban való használatakor érdemes tudni. Bár bármilyen címkét elhelyezhet a dokumentáció megjegyzéseibe, ez a cikk a leggyakoribb nyelvi szerkezetekhez ajánlott címkéket ismerteti. Minden esetben be kell tartania ezeket a javaslatokat:

• A konzisztencia érdekében minden nyilvánosan látható típust és azok nyilvános tagjait dokumentálni kell.
• A privát tagok XML-megjegyzések használatával is dokumentálhatók. Ez azonban elérhetővé teszi a tár belső (potenciálisan bizalmas) működését.
• Minimálisan a típusoknak és tagjaiknak címkével <summary> kell rendelkezniük.
• A dokumentáció szövegét teljes mondatokkal kell megírni.
• A részleges osztályok teljes mértékben támogatottak, és a dokumentáció információi minden típushoz egyetlen bejegyzésbe vannak összefűzve. Ha egy részleges tag mindkét deklarációja rendelkezik dokumentációs megjegyzésekkel, a végrehajtási deklarációra vonatkozó megjegyzések a kimeneti XML-be lesznek írva.

Az XML-dokumentáció a következővel ///kezdődik: . Amikor új projektet hoz létre, a sablonok beírnak néhány kezdővonalat /// . A megjegyzések feldolgozása bizonyos korlátozásokkal rendelkezik:

• A dokumentációnak megfelelően formázott XML-nek kell lennie. Ha az XML nem megfelelően formázott, a fordító figyelmeztetést hoz létre. A dokumentációs fájl tartalmaz egy megjegyzést, amely szerint hiba történt.
• 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. Használat esetén a fordító ellenőrzi, hogy létezik-e a paraméter, és hogy az összes paraméter szerepel-e a dokumentációban. Ha az ellenőrzés sikertelen, a fordító figyelmeztetést ad ki.
  • Az cref attribútum bármely címkéhez csatolható egy kódelemre való hivatkozáshoz. A fordító ellenőrzi, hogy létezik-e ez a kódelem. Ha az ellenőrzés sikertelen, a fordító figyelmeztetést ad ki. A fordító minden utasítást using tiszteletben tart, amikor az cref attribútumban leírt típust keres.
  • A <summary> címkét az IntelliSense használja a Visual Studióban, hogy további információkat jelenítsen meg egy típusról vagy tagról.

    Feljegyzés

    Az XML-fájl nem nyújt teljes információt a típusról és a tagokról (például nem tartalmaz semmilyen típusinformációt). Egy típussal vagy taggal kapcsolatos teljes információ lekéréséhez használja a dokumentációs fájlt a tényleges típusra vagy tagra vonatkozó tükrözéssel együtt.

• A fejlesztők szabadon hozhatnak létre saját címkéket. A fordító ezeket a címkéket a kimeneti fájlba másolja.

Az ajánlott címkék némelyike bármilyen nyelvi elemen használható. Mások speciálisabb használattal rendelkeznek. Végül a címkék némelyike szöveg formázására szolgál a dokumentációban. Ez a cikk a használatuk szerint rendszerezett ajánlott címkéket ismerteti.

A fordító ellenőrzi az elemek szintaxisát, majd egyetlen * karaktert a következő listában. A Visual Studio biztosítja az IntelliSense-t a fordító által ellenőrzött címkékhez és az összes címkéhez, majd ** a következő listában. Az itt felsorolt címkék mellett a fordító és a Visual Studio ellenőrzi a <b>, <i>, <u>, <br/>és <a> a címkéket. A fordító emellett érvényesíti <tt>az elavult HTML-t is.

• Több elemhez használt általános címkék – Ezek a címkék minden API minimális készletét képezik.
  • <summary>: Ennek az elemnek az értéke megjelenik az IntelliSense-ben a Visual Studióban.
  • <remarks> **
• Tagokhoz használt címkék – Ezek a címkék a metódusok és tulajdonságok dokumentálásakor használatosak.
  • <returns>: Ennek az elemnek az értéke megjelenik az IntelliSense-ben a Visual Studióban.
  • <param> *: Ennek az elemnek az értéke megjelenik az IntelliSense-ben a Visual Studióban.
  • <paramref>
  • <exception> *
  • <value>: Ennek az elemnek az értéke megjelenik az IntelliSense-ben a Visual Studióban.
• Dokumentáció kimenetének formázása – Ezek a címkék formázási irányokat biztosítanak a dokumentációt létrehozó eszközökhöz.
  • <para>
  • <list>
  • <c>
  • <code>
  • <example> **
• Dokumentációszöveg újrafelhasználása – Ezek a címkék olyan eszközöket biztosítanak, amelyek megkönnyítik az XML-megjegyzések újrafelhasználását.
  • <inheritdoc> **
  • <include> *
• Hivatkozások és hivatkozások létrehozása – Ezek a címkék más dokumentációkra mutató hivatkozásokat hoznak létre.
  • <see> *
  • <seealso> *
  • cref
  • href
• Általános típusok és metódusok címkéi – Ezeket a címkéket csak általános típusokon és metódusokon használják
  • <typeparam> *: Ennek az elemnek az értéke megjelenik az IntelliSense-ben a Visual Studióban.
  • <typeparamref>

Feljegyzés

A dokumentáció megjegyzései nem alkalmazhatók névtérre.

Ha azt szeretné, hogy szögletes zárójelek jelenjenek meg egy dokumentációs megjegyzés szövegében, használja a html-kódolást<, amely az < > és >a megfelelő. Ez a kódolás az alábbi példában látható.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Általános címkék

<összefoglalás>

<summary>description</summary>

A <summary> címkét egy típus vagy egy típustag leírására kell használni. Megjegyzésekkel <> kiegészítő információkat adhat hozzá egy típusleíráshoz. A cref attribútum használatával engedélyezheti a dokumentációs eszközöket, például a DocFX-et és a Sandcastle-t a kódelemek dokumentációs lapjaira mutató belső hivatkozások létrehozásához. A címke szövege megjelenik az <summary> IntelliSense és az Object Browser ablakban.

<Megjegyzések>

<remarks>
description
</remarks>

A <remarks> címke egy típussal vagy típustaggal kapcsolatos információk hozzáadására szolgál, kiegészítve az összegzéssel>< megadott információkat. Ez az információ az Object Browser ablakban jelenik meg. Ez a címke hosszabb magyarázatokat is tartalmazhat. Előfordulhat, hogy a markdown-szakaszok használata CDATA kényelmesebbé teszi az írást. Az olyan eszközök, mint a docfx , szakaszokban CDATA dolgozzák fel a markdown szöveget.

Dokumentumtagok

<Visszatér>

<returns>description</returns>

A <returns> címkét a metódusdeklaráció megjegyzésében kell használni a visszatérési érték leírásához.

<Param>

<param name="name">description</param>

• name: Egy metódusparaméter neve. A nevet idézőjelek közé ("). A paraméterek nevének meg kell egyeznie az API-aláírásnak. Ha egy vagy több paraméter nincs lefedve, a fordító figyelmeztetést ad ki. A fordító figyelmeztetést is ad, ha az érték name nem egyezik meg a metódusdeklaráció egyik formális paraméterével.

A <param> címkét a metódus deklarációjának megjegyzésében kell használni a metódus egyik paraméterének leírásához. Több paraméter dokumentálásához használjon több címkét <param> . A címke szövege megjelenik az <param> IntelliSense, az Object Browser és a Code Comment webes jelentésben.

<paramref>

<paramref name="name"/>

• name: A hivatkozni kívánt paraméter neve. A nevet idézőjelek közé (").

A <paramref> címke segítségével jelezheti, hogy a kód megjegyzéseiben szereplő szó, például egy <summary> vagy <remarks> egy blokk egy paraméterre hivatkozik. Az XML-fájl feldolgozható úgy, hogy ezt a szót különböző módon formázza, például félkövér vagy dőlt betűtípussal.

<kivétel>

<exception cref="member">description</exception>

• cref = "member": Az aktuális fordítási környezetből elérhető kivételre mutató hivatkozás. A fordító ellenőrzi, hogy létezik-e a megadott kivétel, és a kimeneti XML-ben a canonical elem nevére fordítja member le. member idézőjelek között kell megjelennie (").

A <exception> címke segítségével megadhatja, hogy mely kivételek adhatók meg. Ez a címke alkalmazható metódusok, tulajdonságok, események és indexelők definícióira.

<value>

<value>property-description</value>

A <value> címke lehetővé teszi a tulajdonság által képviselt érték leírását. Amikor a Visual Studio .NET fejlesztői környezetében kódvarázslóval ad hozzá egy tulajdonságot, az hozzáad egy <összefoglaló> címkét az új tulajdonsághoz. Manuálisan hozzáadhat egy címkét <value> a tulajdonság által képviselt érték leírásához.

Dokumentáció kimenetének formázása

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

A <para> címke egy címkén belül használható, például <összegzésre>, <megjegyzésekre> vagy< visszatérésekre>, és lehetővé teszi, hogy struktúrát adjon hozzá a szöveghez. A <para> címke dupla szóközzel tagolt bekezdést hoz létre. Ha egyetlen szóközzel tagolt bekezdést szeretne használni, használja a <br/> címkét.

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

A <listheader> blokk egy tábla vagy definíciólista címsorsorának meghatározására szolgál.

Tábla definiálásakor:

• Csak a címsorban kell megadnia egy bejegyzést term .
• A lista minden eleme blokktal <item> van megadva. Mindegyikhez itemcsak egy bejegyzést kell megadnia description.

Definíciós lista létrehozásakor:

• Meg kell adnia egy bejegyzést term a címsorban.
• A lista minden eleme blokktal <item> van megadva. Mindegyiknek item tartalmaznia kell az a term és descriptiona .

Egy lista vagy tábla annyi blokkot <item> tartalmazhat, amennyi szükséges.

<c>

<c>text</c>

A <c> címke segítségével jelezheti, hogy a leírásban szereplő szöveget kódként kell megjelölni. > Kód használatával <több sort jelölhet kódként.

<code>

<code>
    var index = 5;
    index++;
</code>

A <code> címke több sornyi kód jelzésére szolgál. A c> használatával <jelezheti, hogy a leírásban szereplő egysoros szöveget kódként kell megjelölni.

<példa>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

A <example> címke segítségével megadhat egy példát egy metódus vagy más kódtártag használatára. Ilyen például a <kódcímke> használata.

Dokumentáció szövegének újrafelhasználása

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

XML-megjegyzéseket örököl az alaposztályokból, interfészekből és hasonló metódusokból. A használat inheritdoc kiküszöböli a duplikált XML-megjegyzések nem kívánt másolását és beillesztését, és automatikusan szinkronizálja az XML-megjegyzéseket. Amikor hozzáadja a <inheritdoc> címkét egy típushoz, minden tag örökli a megjegyzéseket is.

• cref: Adja meg azt a tagot, akitől a dokumentációt örökölni szeretné. Az aktuális tagon már definiált címkéket az örököltek nem bírálják felül.
• path: Az XPath kifejezés lekérdezése, amely egy megjelenítendő csomópontkészletet eredményez. Ezzel az attribútummal szűrheti a címkéket, hogy belefoglalják vagy kizárják az örökölt dokumentációból.

Adja hozzá az XML-megjegyzéseket az alaposztályokhoz vagy felületekhez, és hagyja, hogy az inheritdoc átmásolja a megjegyzéseket az implementálási osztályokba. Adja hozzá az XML-megjegyzéseket a szinkron metódusaihoz, és hagyja, hogy az inheritdoc átmásolja a megjegyzéseket ugyanazon metódusok aszinkron verzióiba. Ha egy adott tag megjegyzéseit szeretné másolni, az cref attribútum használatával adja meg a tagot.

<tartalmaz>

<include file='filename' path='tagpath[@name="id"]' />

• filename: A dokumentációt tartalmazó XML-fájl neve. A fájlnév a forráskódfájlhoz viszonyított elérési úttal minősíthető. Idézőjelek filename közé (' ') ágyazva.
• tagpath: Annak a címkéknek az elérési útja, amely filename a címkéhez namevezet. Az elérési utat egyetlen idézőjelbe (' ') kell foglalnia.
• name: A megjegyzéseket megelőző címke névkijelölője; name van egy id.
• id: A megjegyzéseket megelőző címke azonosítója. Az azonosítót idézőjelek közé (").

A <include> címke segítségével egy másik fájlban található megjegyzésekre hivatkozhat, amelyek a forráskódban szereplő típusokat és tagokat írják le. A külső fájlokat is beleszámítva a dokumentáció megjegyzéseit közvetlenül a forráskódfájlba helyezheti. Ha a dokumentációt külön fájlba helyezi, a forráskódtól elkülönítve alkalmazhatja a forrásvezérlőt a dokumentációra. Egy személy kiveheti a forráskódfájlt, valaki más pedig kiveheti a dokumentációs fájlt. A <include> címke az XML XPath szintaxist használja. A használat testreszabásának módjaiért tekintse meg az XPath dokumentációját <include> .

A következő forráskód például a <include> címkét használja megjegyzések belefoglalására. A fájl elérési útja a forráshoz képest van.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

A belefoglaló fájl XML-forrása az alábbi példában látható. Felépítése megegyezik a C#-fordító által létrehozott XML-fájllal. Az XML-fájl több metódushoz vagy típushoz is tartalmazhat szöveget, amennyiben egy XPath-kifejezés azonosítja őket.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

A metódus XML-kimenete a következő példában látható:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Tipp.

A .NET Futtatókörnyezet csapata a címkét széles körben használja a <include> dokumentációjában. Számos példát láthat az dotnet/runtime adattárban való kereséssel.

Hivatkozások és hivatkozások létrehozása

<lát>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>

• cref="member": Az aktuális összeállítási környezetből meghívható tagra vagy mezőre mutató hivatkozás. A fordító ellenőrzi, hogy a megadott kódelem létezik-e, és a kimeneti XML-fájlban adja-e át member az elem nevét. Tag elhelyezése idézőjelek közé ("). A "cref"-hez különböző hivatkozásszöveget adhat meg egy külön zárócímkével.
• href="link": Egy adott URL-címre mutató kattintható hivatkozás. Például egy kattintható hivatkozást hoz létre olyan <see href="https://github.com">GitHub</see> szöveggel GitHub , amely a hivatkozásra https://github.commutat.
• langword="keyword": Egy nyelvi kulcsszó, például true egy másik érvényes kulcsszó.

A <see> címke lehetővé teszi a szövegen belüli hivatkozás megadását. A seealso> használatával <jelezheti, hogy a szöveget egy Lásd még szakaszba kell helyezni. A cref attribútum használatával belső hivatkozásokat hozhat létre a kódelemek dokumentációs lapjaira. A típusparaméterekkel általános típusra vagy metódusra mutató hivatkozást adhat meg, például cref="IDictionary{T, U}". Emellett egy érvényes attribútum, href amely hivatkozásként működik.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>

• cref="member": Az aktuális összeállítási környezetből meghívható tagra vagy mezőre mutató hivatkozás. A fordító ellenőrzi, hogy a megadott kódelem létezik-e, és a kimeneti XML-fájlban adja-e át member az elem nevét. member idézőjelek között kell megjelennie (").
• href="link": Egy adott URL-címre mutató kattintható hivatkozás. Például egy kattintható hivatkozást hoz létre olyan <seealso href="https://github.com">GitHub</seealso> szöveggel GitHub , amely a hivatkozásra https://github.commutat.

A <seealso> címke segítségével megadhatja, hogy milyen szöveg jelenjen meg egy Lásd még szakaszban. > Itt <adhatja meg a szövegen belüli hivatkozást. A címke nem ágyazható seealso be a summary címkébe.

cref attribútum

Az cref XML-dokumentáció címkéjében szereplő attribútum "kódhivatkozást" jelent. Meghatározza, hogy a címke belső szövege kódelem, például típus, metódus vagy tulajdonság. Az olyan dokumentációs eszközök, mint a DocFX és a Sandcastle , az cref attribútumokkal automatikusan létrehoznak hivatkozásokat arra a lapra, amelyen a típus vagy tag dokumentálva van.

href attribútum

Az href attribútum egy weblapra mutató hivatkozást jelent. Segítségével közvetlenül hivatkozhat az API-ra vagy a tárra vonatkozó online dokumentációra.

Általános típusok és metódusok

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>

• TResult: A típusparaméter neve. A nevet idézőjelek közé (").

A <typeparam> címkét egy általános típus- vagy metódusdeklaráció megjegyzésében kell használni egy típusparaméter leírásához. Adjon hozzá egy címkét az általános típus vagy metódus egyes típusparamétereihez. A címke szövege megjelenik az <typeparam> IntelliSense-ben.

<typeparamref>

<typeparamref name="TKey"/>

• TKey: A típusparaméter neve. A nevet idézőjelek közé (").

Ezzel a címkével lehetővé teheti a dokumentációs fájl felhasználói számára, hogy a szót különböző módon, például dőlt betűvel formázhassák.

Felhasználó által definiált címkék

A cikkben ismertetett címkék a C#-fordító által felismert címkéket jelölik. A felhasználók azonban szabadon definiálhatják saját címkéiket. Az olyan eszközök, mint a Sandcastle, támogatják az olyan további címkéket, mint az <esemény> és <a jegyzet>, és még a névterek dokumentálását is támogatják. A szabványos címkékkel egyéni vagy házon belüli dokumentációkészítési eszközök is használhatók, és a HTML-ről PDF-be több kimeneti formátum is támogatott.