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.

A C# nyelv referenciadokumentuma a C# nyelv legújabb kiadású verzióját ismerteti. Emellett a közelgő nyelvi kiadás nyilvános előzetes verziójú funkcióinak kezdeti dokumentációját is tartalmazza.

A dokumentáció azonosítja azokat a funkciókat, amelyeket először a nyelv utolsó három verziójában vagy az aktuális nyilvános előzetes verziókban vezetnek be.

Tipp.

Ha meg szeretné tudni, hogy mikor jelent meg először egy funkció a C#-ban, tekintse meg a C# nyelvi verzióelőzményeiről szóló cikket.

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. Tartsa be ezeket a javaslatokat:

  • A konzisztencia érdekében dokumentálja az összes nyilvánosan látható típust és azok nyilvános tagjait.
  • A privát tagokat XML-megjegyzések használatával is dokumentálhatja. Ez a megközelítés azonban elérhetővé teszi a könyvtár belső (potenciálisan bizalmas) működését.
  • Minimálisan a típusoknak és tagjaiknak címkével <summary> kell rendelkezniük.
  • Dokumentációs szöveg írása teljes mondatokkal, amelyek teljes leállásokkal végződnek.
  • 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étereket írja le. Ha ezt a címkét használja, 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.
    • Csatolja az cref attribútumot bármely címkéhez 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 Visual Studio belüli IntelliSense a <summary> címkével jelenít meg további információkat 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. Visual Studio intelliSense-t biztosí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őrzik a <b>, <i>, <u>, <br/> és <a> címkéket. A fordító emellett érvényesíti <tt>az elavult HTML-t is.

Feljegyzés

A HTML-címkék, például <br/> a dokumentáció megjegyzéseinek formázásához hasznosak. A <br/> címke sortöréseket hoz létre, míg más HTML-címkék szövegformázást biztosítanak. Ezek a címkék az IntelliSense elemleírásaiban és a létrehozott dokumentációban működnek.

Feljegyzés

Nem alkalmazhat dokumentációs megjegyzéseket 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 >&lt; és &gt;a megfelelő. Az alábbi példa ezt a kódolást mutatja be.

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

Általános címkék

<summary>

<summary>description</summary>

A címke egy <summary> típus vagy egy típustag leírására használható. Kiegészítő <remarks> 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.

<remarks>

<remarks>
description
</remarks>

<remarks> A címkével adatokat adhat meg egy típusról vagy egy típustagról, kiegészítve a megadott <summary>információkkal. Ez az információ megjelenik az Object Browser ablakban. 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

<returns>

<returns>description</returns>

A visszatérési érték leírásához használja a <returns> megjegyzésben szereplő címkét egy metódusdeklaráció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.

<param> A metódus deklarációjának megjegyzésében szereplő címkével írja le a metódus egyik paraméterét. 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 lehetővé teszi annak jelzését, 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 eltérő módon formázza, például félkövér vagy dőlt betűtípussal.

<exception>

<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. Alkalmazza ezt a címkét a 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. Ha a Visual Studio .NET fejlesztői környezetben a kódvarázslóval ad hozzá egy tulajdonságot, <summary> címkét ad hozzá 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>

<para> A címkén belüli címkével ( például <summary>, <remarks>, vagy <returns>) struktúrát adhat 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.

Íme egy példa, amely a következők közötti <para><br/>különbséget mutatja be:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<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>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</description>
    </item>
</list>

<listheader> A blokk használatával meghatározhatja egy tábla vagy definíciólista címsorsorát.

Tábla definiálásakor:

  • Adjon meg egy bejegyzést term a címsorban.
  • Adja meg a lista minden elemét egy <item> blokktal. Mindegyikhez itemadjon meg egy bejegyzést.description

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

  • Adjon meg egy bejegyzést term a címsorban.
  • Adja meg a lista minden elemét egy <item> blokktal. 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ímkével <c> kódként jelölhet meg szöveget egy leírásban. Több <code> sort jelölhet kódként.

<code>

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

A címkével <code> több kódsort jelölhet. Egysoros <c> szöveg megjelölése egy leírásban kódként.

<example>

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

<example> A címkével példát mutathat egy metódus vagy más kódtártag használatára. Ilyen például a <code> címke használata.

<b>

<b>text</b>

A címkével <b> félkövérré teheti a szöveget a dokumentáció megjegyzései között. A fordító és Visual Studio érvényesíteni ezt a HTML-formázási címkét. A formázott szöveg megjelenik az IntelliSense-ben és a létrehozott dokumentációban.

<i>

<i>text</i>

A címkével <i> dőlt szöveget készíthet a dokumentáció megjegyzései között. A fordító és Visual Studio érvényesíteni ezt a HTML-formázási címkét. A formázott szöveg megjelenik az IntelliSense-ben és a létrehozott dokumentációban.

<u>

<u>text</u>

A címkével <u> aláhúzhatja a szöveget a dokumentáció megjegyzései között. A fordító és Visual Studio érvényesíteni ezt a HTML-formázási címkét. A formázott szöveg megjelenik az IntelliSense-ben és a létrehozott dokumentációban.

<br/>

Line one<br/>Line two

A címkével <br/> sortörést szúrhat be a dokumentáció megjegyzéseibe. Ezt a címkét akkor használja, ha egyetlen szóközzel rendelkező bekezdést szeretne használni, szemben a <para> dupla szóközzel tagolt bekezdéseket létrehozó címkével.

<a>

<a href="https://example.com">Link text</a>

A címkével <a> hivatkozásokat hozhat létre a dokumentáció megjegyzései között. Az href attribútum megadja a hivatkozni kívánt URL-címet. A fordító és Visual Studio érvényesíteni ezt a HTML-formázási címkét.

Feljegyzés

A fordító emellett ellenőrzi az <tt> elavult HTML-kódú címkét is. Használja inkább a <c> címkét beágyazott kódformázáshoz.

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ával inheritdockiküszöbölheti a duplikált XML-megjegyzések nem kívánt másolását és beillesztését, és automatikusan szinkronizálhatja 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 örökölt címkék nem bírálják felül az aktuális tagon már definiált címkéket.
  • 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.

Feljegyzés

Visual Studio automatikusan örökli a dokumentált tagokat felülbíráló vagy implementáló, nem dokumentált tagok XML-dokumentációját. Ez a funkció az Örökölt dokumentációt jeleníti meg az IntelliSense-ben és a Gyors információban a <inheritdoc> címke megkövetelése nélkül. Ez az automatikus öröklés azonban csak a Visual Studio IDE vonatkozik, és nincs hatással a fordító által létrehozott XML-dokumentációs fájlra.

Az ön által terjesztett kódtárak nyilvános API-k esetében explicit módon használja a <inheritdoc> címkét, vagy adjon meg teljes dokumentációt annak biztosítására, hogy a létrehozott XML-dokumentációs fájl tartalmazza a tár felhasználói számára szükséges összes információt.

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. Egy adott tag megjegyzéseinek másolásához használja az cref attribútumot a tag megadásához.

<include>

<include file='filename' path='tagpath' />
<include file='filename' path='tagpath[@attribName]' />
<include file='filename' path='tagpath[@attribName="attribValue"]' />
<include file='filename' path='tagpath[@attribName1="attribValue1"][@attribName2="attribValue2"][@attribName3]' />

Javaslat:

<include file='filename' path='tagpath[@name="id"]' />
  • filename: A dokumentációt tartalmazó XML-fájl neve. A fájlnevet a forráskódfájlhoz viszonyított elérési úttal minősítheti. Idézőjelek filename közé (' ') ágyazva.
  • path: A címkék filename elérési útja, amely a használni kívánt XML-megjegyzéshez vezet. Az elérési út tartalmazhat egy vagy több attribútumot, például name, de nem kötelező. Előfordulhat, hogy az attribútumok olyan értékekkel rendelkeznek, mint a id, de az értékekre sincs szükség. Csatolja az elérési utat, beleértve a lehetséges attribútumokat egyetlen idézőjelbe (' ').
  • attribName, attribName1: Az opcionális attribútumok nevei.
  • attribValue, attribValue1: Az attribútumok választható értékei. Ha nincs megadva érték, a rendszer bármilyen értéket elfogad a megjegyzés keresésekor a következőben filename: . Az attribútum értékét idézőjelek közé (").

A címke használatával <include> egy másik fájlban lévő megjegyzésekre hivatkozhat, amelyek a forráskód típusait és tagjait í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 dokumentációjában széles körben használja a <include> címkét. Számos példát láthat az dotnet/runtime adattárban való kereséssel.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": Egy tagra vagy mezőre mutató hivatkozás, amelyet az aktuális összeállítási környezetből hívhat meg. 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é ("). Egy külön zárócímke használatával különböző hivatkozásszövegeket crefadhat meg.
  • href="link": Egy adott URL-címre mutató kattintható hivatkozás. A <see href="https://github.com">GitHub</see> például a https://github.com hivatkozásra mutató szöveggel GitHub kattintva kattintható hivatkozást hoz létre. href Ahelyett, cref hogy külső weblapokra mutató hivatkozásokat hozna létre, mint a cref kódhivatkozásokhoz, és nem hoz létre kattintható hivatkozásokat külső URL-címekhez.
  • 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. Azt <seealso> jelzi, 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. Adja meg a típusparamétereket egy általános típusra vagy metódusra való hivatkozás megadásához, például cref="IDictionary{T, U}". Emellett egy érvényes attribútum, href amely hivatkozásként működik.

Íme egy példa a külső URL-címekre való hivatkozás különbségére crefhref :

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Egy tagra vagy mezőre mutató hivatkozás, amelyet az aktuális összeállítási környezetből hívhat meg. 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. A <seealso href="https://github.com">GitHub</seealso> például a https://github.com hivatkozásra mutató szöveggel GitHub kattintva kattintható hivatkozást hoz létre.

A <seealso> címke segítségével megadhatja, hogy milyen szöveg jelenjen meg egy Lásd még szakaszban. A szövegen belüli hivatkozás megadására használható <see> . 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. Ha külső URL-címekre kell hivatkoznia a dokumentáció megjegyzéseiben, az href elemet használja ahelyett cref-t, hogy a hivatkozások rákattinthatók lehessenek az IntelliSense eszköztippeiben és a létrehozott dokumentációban.

Á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 <event> and <note>, é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.

  • Last updated on