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

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.

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

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 >&lt; és &gt;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

<summary>

<summary>description</summary>

A <summary> címkét egy típus vagy egy típustag leírására kell használni. 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>

A <remarks> címke egy típussal vagy típustaggal kapcsolatos információk hozzáadására szolgál, kiegészítve a megadott <summary>információkkal. 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

<returns>

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

<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. 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 címkét <summary> 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 <summary>, <remarks>vagy <returns>, és lehetővé teszi a szerkezet hozzáadását 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>
</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. Több <code> 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. Azt <c> jelzi, hogy a leírásban szereplő egysoros szöveget kódként kell megjelölni.

<example>

<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 <code> címke használata.

<b>

<b>text</b>

A <b> címkével félkövér szöveg jeleníthető meg a dokumentáció megjegyzései között. Ezt a HTML-formázási címkét a fordító és a Visual Studio érvényesíti, és a formázott szöveg megjelenik az IntelliSense-ben és a létrehozott dokumentációban.

<i>

<i>text</i>

A <i> címke a szöveg dőlté tételére szolgál a dokumentációs megjegyzésekben. Ezt a HTML-formázási címkét a fordító és a Visual Studio érvényesíti, és a formázott szöveg megjelenik az IntelliSense-ben és a létrehozott dokumentációban.

<u>

<u>text</u>

A <u> címke a dokumentációs megjegyzések szövegének aláhúzására szolgál. Ezt a HTML-formázási címkét a fordító és a Visual Studio érvényesíti, és a formázott szöveg megjelenik az IntelliSense-ben és a létrehozott dokumentációban.

<br/>

Line one<br/>Line two

A <br/> címke segítségével 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 <a> címke hivatkozásokat hoz létre a dokumentáció megjegyzései között. Az href attribútum megadja a hivatkozni kívánt URL-címet. Ezt a HTML-formázási címkét a fordító és a Visual Studio érvényesíti.

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

Feljegyzés

A Visual Studio automatikusan örököli az XML-dokumentációt a dokumentált tagokat felülbíráló vagy implementáló nem dokumentált tagok számára. 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-ben érvényes, é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-jai esetében kifejezetten használja a <inheritdoc> címkét, vagy adjon meg teljes dokumentációt annak érdekében, 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. Ha egy adott tag megjegyzéseit szeretné másolni, az cref attribútum használatával adja meg a tagot.

<include>

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

<see>

<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. Használja a href a cref helyett, amikor külső weblapokra mutató hivatkozásokat hoz létre, mivel a cref a kódhivatkozásokhoz lett tervezve, és nem hoz létre kattintható hivatkozásokat a 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. 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.

Í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": 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. 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