Zalecane tagi XML dla komentarzy dokumentacji języka C#

  • Artykuł

Komentarze dokumentacji języka C# używają elementów XML do definiowania struktury dokumentacji wyjściowej. Jedną z konsekwencji tej funkcji jest dodanie dowolnego prawidłowego kodu XML w komentarzach dokumentacji. Kompilator języka C# kopiuje te elementy do wyjściowego pliku XML. Chociaż w komentarzach można używać dowolnego prawidłowego kodu XML (w tym dowolnego prawidłowego elementu HTML), z wielu powodów zaleca się dokumentowanie kodu.

Poniżej przedstawiono kilka zaleceń, ogólnych scenariuszy przypadków użycia i rzeczy, które należy wiedzieć podczas korzystania z tagów dokumentacji XML w kodzie języka C#. Chociaż można umieścić dowolne tagi w komentarzach dokumentacji, w tym artykule opisano zalecane tagi dla najbardziej typowych konstrukcji języka. We wszystkich przypadkach należy przestrzegać następujących zaleceń:

  • Ze względu na spójność należy udokumentować wszystkie publicznie widoczne typy i ich publiczne elementy członkowskie.
  • Prywatne elementy członkowskie można również udokumentować przy użyciu komentarzy XML. Uwidacznia jednak wewnętrzne (potencjalnie poufne) działanie biblioteki.
  • Na minimalnym poziomie typy i ich członkowie powinni mieć <summary> tag.
  • Tekst dokumentacji powinien być napisany przy użyciu pełnych zdań kończących się pełnymi zatrzymaniami.
  • Klasy częściowe są w pełni obsługiwane, a informacje o dokumentacji zostaną łączone w jeden wpis dla każdego typu.

Dokumentacja XML rozpoczyna się od ///. Podczas tworzenia nowego projektu szablony umieszczają kilka /// początkowych wierszy. Przetwarzanie tych komentarzy ma pewne ograniczenia:

  • Dokumentacja musi być poprawnie sformułowanym kodem XML. Jeśli kod XML nie jest poprawnie sformułowany, kompilator generuje ostrzeżenie. Plik dokumentacji będzie zawierać komentarz informujący, że wystąpił błąd.
  • Niektóre z zalecanych tagów mają specjalne znaczenie:
    • Tag <param> służy do opisywania parametrów. Jeśli jest używany, kompilator sprawdza, czy parametr istnieje i czy wszystkie parametry zostały opisane w dokumentacji. Jeśli weryfikacja zakończy się niepowodzeniem, kompilator wyświetla ostrzeżenie.
    • Atrybut cref można dołączyć do dowolnego tagu, aby odwoływać się do elementu kodu. Kompilator sprawdza, czy ten element kodu istnieje. Jeśli weryfikacja zakończy się niepowodzeniem, kompilator wyświetla ostrzeżenie. Kompilator uwzględnia wszelkie using instrukcje, gdy szuka typu opisanego w atrybucie cref .
    • Tag <summary> jest używany przez funkcję IntelliSense w programie Visual Studio do wyświetlania dodatkowych informacji o typie lub elemencie członkowskim.

      Uwaga

      Plik XML nie zawiera pełnych informacji o typie i elementach członkowskich (na przykład nie zawiera żadnych informacji o typie). Aby uzyskać pełne informacje o typie lub elemencie członkowskim, użyj pliku dokumentacji wraz z odbiciem rzeczywistego typu lub elementu członkowskiego.

  • Deweloperzy mogą tworzyć własny zestaw tagów. Kompilator skopiuje je do pliku wyjściowego.

Niektóre z zalecanych tagów mogą być używane w dowolnym elemecie języka. Inne mają bardziej wyspecjalizowane użycie. Na koniec niektóre tagi są używane do formatowania tekstu w dokumentacji. W tym artykule opisano zalecane tagi uporządkowane według ich użycia.

Kompilator weryfikuje składnię elementów, po których następuje jeden * na poniższej liście. Program Visual Studio udostępnia funkcję IntelliSense dla tagów zweryfikowanych przez kompilator i wszystkie tagi, po których następuje ** na poniższej liście. Oprócz tagów wymienionych tutaj kompilator i program Visual Studio weryfikują <b>tagi , , <i><u>, <br/>i <a> . Kompilator weryfikuje <tt>również element , który jest przestarzałym kodem HTML.

Uwaga

Nie można zastosować komentarzy dokumentacji do przestrzeni nazw.

Jeśli chcesz, aby nawiasy kątowe były wyświetlane w tekście komentarza dokumentacji, należy użyć kodowania < HTML i >, który jest &lt; i &gt; odpowiednio. To kodowanie jest pokazane w poniższym przykładzie.

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

Tagi ogólne

<Krótki opis>

<summary>description</summary>

Tag <summary> powinien służyć do opisywania typu lub elementu członkowskiego typu. Użyj <uwag> , aby dodać informacje uzupełniające do opisu typu. Użyj atrybutu cref, aby włączyć narzędzia dokumentacji, takie jak DocFX i Sandcastle, aby utworzyć wewnętrzne hiperłącza do stron dokumentacji dla elementów kodu. Tekst tagu <summary> jest wyświetlany w funkcji IntelliSense i w oknie Przeglądarka obiektów.

<Uwagi>

<remarks>
description
</remarks>

Tag <remarks> służy do dodawania informacji o typie lub elemencie członkowskim typu, uzupełniając informacje określone za pomocą <podsumowania>. Te informacje są wyświetlane w oknie Przeglądarka obiektów. Ten tag może zawierać bardziej długie wyjaśnienia. Może się okazać, że użycie CDATA sekcji dla języka Markdown sprawia, że pisanie go jest wygodniejsze. Narzędzia, takie jak docfx , przetwarzają tekst markdown w CDATA sekcjach.

Elementy członkowskie dokumentu

<Zwraca>

<returns>description</returns>

Tag <returns> powinien być używany w komentarzu dla deklaracji metody w celu opisania wartości zwracanej.

<Param>

<param name="name">description</param>
  • name: nazwa parametru metody. Ujęć nazwę w podwójny cudzysłów (" "). Nazwy parametrów muszą być zgodne z podpisem interfejsu API. Jeśli co najmniej jeden parametr nie jest omówiony, kompilator wyświetla ostrzeżenie. Kompilator wyświetla również ostrzeżenie, jeśli wartość parametru name nie jest zgodna z parametrem formalnym w deklaracji metody.

Tag <param> powinien być używany w komentarzu dla deklaracji metody, aby opisać jeden z parametrów metody. Aby udokumentować wiele parametrów, użyj wielu <param> tagów. Tekst tagu <param> jest wyświetlany w funkcji IntelliSense, przeglądarce obiektów i raporcie sieci Web komentarza kodu.

<paramref>

<paramref name="name"/>
  • name: nazwa parametru do odwoływania się do. Ujęć nazwę w podwójny cudzysłów (" ").

Tag <paramref> umożliwia wskazanie, że słowo w komentarzach kodu, na przykład w <summary> bloku lub <remarks> odnosi się do parametru. Plik XML można przetworzyć w celu sformatowania tego wyrazu w inny sposób, na przykład przy użyciu czcionki pogrubionej lub kursywy.

<Wyjątek>

<exception cref="member">description</exception>
  • cref = "member": odwołanie do wyjątku dostępnego w bieżącym środowisku kompilacji. Kompilator sprawdza, czy dany wyjątek istnieje i przekłada się member na nazwę elementu kanonicznego w wyjściowym pliku XML. member musi znajdować się w podwójnym cudzysłowie (" ").

Tag <exception> umożliwia określenie, które wyjątki mogą być zgłaszane. Ten tag można zastosować do definicji metod, właściwości, zdarzeń i indeksatorów.

<wartość>

<value>property-description</value>

Tag <value> umożliwia opisanie wartości reprezentowanej przez właściwość. Po dodaniu właściwości za pomocą kreatora kodu w środowisku programistycznym .NET programu Visual Studio dodaje <tag podsumowania> dla nowej właściwości. Należy ręcznie dodać tag, <value> aby opisać wartość, którą reprezentuje właściwość.

Formatowanie danych wyjściowych dokumentacji

<para>

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

Tag <para> służy do użycia wewnątrz tagu, takiego jak< podsumowanie>, <uwagi> lub< zwraca,> i umożliwia dodawanie struktury do tekstu. Tag <para> tworzy dwukrotnie rozmieszczony akapit. Użyj tagu <br/> , jeśli chcesz utworzyć pojedynczy akapit spacji.

<lista>

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

Blok <listheader> służy do definiowania wiersza nagłówka tabeli lub listy definicji. Podczas definiowania tabeli wystarczy podać wpis w term nagłówku. Każdy element na liście jest określony z blokiem <item> . Podczas tworzenia listy definicji należy określić wartości i termdescription. Jednak w przypadku tabeli, listy punktowanej lub listy numerowanej wystarczy podać wpis dla descriptionelementu . Lista lub tabela może zawierać tyle <item> bloków, ile jest potrzebnych.

<C>

<c>text</c>

Tag <c> umożliwia wskazanie, że tekst w opisie powinien być oznaczony jako kod. Użyj <kodu> , aby wskazać wiele wierszy jako kod.

<kod>

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

Tag <code> służy do wskazywania wielu wierszy kodu. Użyj <języka c> , aby wskazać, że tekst jednowierszowy w opisie powinien być oznaczony jako kod.

<Przykład>

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

Tag <example> umożliwia określenie przykładu użycia metody lub innego elementu członkowskiego biblioteki. Przykładem często jest użycie tagu <kodu> .

Ponowne używanie tekstu dokumentacji

<inheritdoc>

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

Dziedzicz komentarze XML z klas bazowych, interfejsów i podobnych metod. Użycie inheritdoc eliminuje niepożądane kopiowanie i wklejanie zduplikowanych komentarzy XML i automatycznie przechowuje synchronizowane komentarze XML. Pamiętaj, że po dodaniu tagu <inheritdoc> do typu wszystkie elementy członkowskie również dziedziczą komentarze.

  • cref: Określ element członkowski do dziedziczenia dokumentacji. Już zdefiniowane tagi na bieżącym elemencie członkowskim nie są zastępowane przez dziedziczone.
  • path: zapytanie wyrażenia XPath, które spowoduje wyświetlenie węzła ustawionego na wartość . Tego atrybutu można użyć do filtrowania tagów w celu uwzględnienia lub wykluczenia z dziedziczonej dokumentacji.

Dodaj komentarze XML w klasach bazowych lub interfejsach i pozwól dziedziczyć komentarze do implementowania klas. Dodaj komentarze XML do metod synchronicznych i pozwól dziedziczyć komentarze do asynchronicznych wersji tych samych metod. Jeśli chcesz skopiować komentarze z określonego elementu członkowskiego, użyj atrybutu cref , aby określić element członkowski.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: nazwa pliku XML zawierającego dokumentację. Nazwę pliku można zakwalifikować przy użyciu ścieżki względem pliku kodu źródłowego. Ujęć filename w pojedynczy cudzysłów (' ').
  • tagpath: ścieżka tagów w filename pliku , która prowadzi do tagu name. Ujęć ścieżkę w pojedynczy cudzysłów (' ').
  • name: specyfikator nazwy w tagu poprzedzającym komentarze; name element będzie miał element id.
  • id: identyfikator tagu, który poprzedza komentarze. Ujęć identyfikator w podwójny cudzysłów (" ").

Tag <include> umożliwia odwoływanie się do komentarzy w innym pliku, które opisują typy i elementy członkowskie w kodzie źródłowym. Dołączenie pliku zewnętrznego jest alternatywą do umieszczania komentarzy dokumentacji bezpośrednio w pliku kodu źródłowego. Umieszczając dokumentację w osobnym pliku, możesz stosować kontrolę źródła do dokumentacji oddzielnie od kodu źródłowego. Jedna osoba może mieć wyewidencjonowany plik kodu źródłowego, a inna osoba może mieć wyewidencjonowany plik dokumentacji. Tag <include> używa składni XPath XML. Zapoznaj się z dokumentacją programu XPath, aby uzyskać informacje na temat sposobów dostosowywania <include> użycia.

Na przykład poniższy kod źródłowy używa tagu <include> do uwzględnienia uwag. Ścieżka pliku jest względna względem źródła.

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

Źródło XML pliku dołączania jest pokazane w poniższym przykładzie. Jest on ustrukturyzowany tak samo jak plik XML wygenerowany przez kompilator języka C#. Plik XML może zawierać tekst dla wielu metod lub typów, o ile wyrażenie XPath może je zidentyfikować.

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

Dane wyjściowe XML dla tej metody są wyświetlane w poniższym przykładzie:

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

Napiwek

Zespół środowiska uruchomieniowego platformy .NET używa tagu <include> szeroko w swojej dokumentacji. Możesz wyświetlić wiele przykładów, wyszukując dotnet/runtime repozytorium.

<Zobacz>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": odwołanie do elementu członkowskiego lub pola, które jest dostępne do wywołania z bieżącego środowiska kompilacji. Kompilator sprawdza, czy dany element kodu istnieje i przekazuje member do nazwy elementu w wyjściowym kodzie XML. Umieść element członkowski w podwójnym cudzysłowie (" "). Możesz podać inny tekst linku dla "cref", używając oddzielnego tagu zamykającego.
  • href="link": link do kliknięcia do danego adresu URL. Na przykład <see href="https://github.com">GitHub</see> tworzy link do kliknięcia z tekstem GitHub , który łączy się z https://github.comelementem .
  • langword="keyword": słowo kluczowe języka, takie jak true lub jedno z innych prawidłowych słów kluczowych.

Tag <see> umożliwia określenie linku z poziomu tekstu. Użyj <polecenia seealso> , aby wskazać, że tekst powinien zostać umieszczony w sekcji Zobacz również. Użyj atrybutu cref, aby utworzyć wewnętrzne hiperłącza do stron dokumentacji dla elementów kodu. Parametry typu należy uwzględnić, aby określić odwołanie do typu ogólnego lub metody, na przykład cref="IDictionary{T, U}". href Ponadto jest prawidłowym atrybutem, który będzie działać jako hiperlink.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": odwołanie do elementu członkowskiego lub pola, które jest dostępne do wywołania z bieżącego środowiska kompilacji. Kompilator sprawdza, czy dany element kodu istnieje i przekazuje member do nazwy elementu w wyjściowym kodzie XML. member musi znajdować się w podwójnym cudzysłowie (" ").
  • href="link": link do kliknięcia do danego adresu URL. Na przykład <seealso href="https://github.com">GitHub</seealso> tworzy link do kliknięcia z tekstem GitHub , który łączy się z https://github.comelementem .

Tag <seealso> umożliwia określenie tekstu, który może być wyświetlany w sekcji Zobacz również . Użyj <polecenia see> , aby określić link z poziomu tekstu. Nie można zagnieżdżać tagu seealso wewnątrz tagu summary .

Atrybut cref

Atrybut cref w tagu dokumentacji XML oznacza "odwołanie do kodu". Określa, że tekst wewnętrzny tagu jest elementem kodu, takim jak typ, metoda lub właściwość. Narzędzia dokumentacji, takie jak DocFX i Sandcastle , używają cref atrybutów do automatycznego generowania hiperlinków na stronie, na której udokumentowano typ lub element członkowski.

atrybut href

Atrybut href oznacza odwołanie do strony internetowej. Można go używać do bezpośredniego odwoływania się do dokumentacji online dotyczącej interfejsu API lub biblioteki.

Typy ogólne i metody

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: nazwa parametru typu. Ujęć nazwę w podwójny cudzysłów (" ").

Tag <typeparam> powinien być używany w komentarzu dla deklaracji typu ogólnego lub metody w celu opisania parametru typu. Dodaj tag dla każdego parametru typu typu typu lub metody ogólnej. Tekst tagu <typeparam> zostanie wyświetlony w funkcji IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: nazwa parametru typu. Ujęć nazwę w podwójny cudzysłów (" ").

Użyj tego tagu, aby umożliwić konsumentom pliku dokumentacji formatowanie wyrazu w inny sposób, na przykład kursywą.

Tagi zdefiniowane przez użytkownika

Wszystkie opisane powyżej tagi reprezentują te tagi, które są rozpoznawane przez kompilator języka C#. Użytkownik może jednak definiować własne tagi. Narzędzia, takie jak Sandcastle, obsługują dodatkowe tagi, takie jak <zdarzenia> i< notatki>, a nawet obsługują dokumentowanie przestrzeni nazw. Niestandardowe lub wewnętrzne narzędzia do generowania dokumentacji mogą być również używane z tagami standardowymi, a można obsługiwać wiele formatów wyjściowych z kodu HTML do formatu PDF.