Dokumentuj swój kod za pomocą komentarzy XML

Dokumentację można utworzyć na podstawie komentarzy kodu triple-slash (///) w języku F#. Komentarze XML mogą poprzedzać deklaracje w plikach kodu (.fs) lub w plikach podpisu (fsi).

Komentarze dokumentacji XML są specjalnym rodzajem komentarza dodanego powyżej definicji dowolnego typu lub elementu członkowskiego zdefiniowanego przez użytkownika. Są one specjalne, ponieważ mogą być przetwarzane przez kompilator w celu wygenerowania pliku dokumentacji XML w czasie kompilacji. Plik XML wygenerowany przez kompilator może być dystrybuowany wraz z zestawem platformy .NET, tak aby środowiska IDE mogły używać podpowiedzi do wyświetlania szybkich informacji o typach lub elementach członkowskich. Ponadto plik XML można uruchamiać za pomocą narzędzi, takich jak fsdocs do generowania witryn referencyjnych interfejsu API.

Domyślnie komentarze dokumentacji XML są ignorowane przez kompilator. Aby to zmienić, ustaw --warnon:3390. Kompilator zweryfikuje następnie składnię kodu XML oraz parametry określone w tagach <param> i <paramref>.

Plik XML można wygenerować w czasie kompilacji, wykonując jedną z następujących czynności:

• Element GenerateDocumentationFile można dodać do sekcji <PropertyGroup> pliku projektu .fsproj, który generuje plik XML w katalogu projektu z tą samą główną nazwą pliku co zestaw. Na przykład:

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

  Aby uzyskać więcej informacji, zobacz właściwość GenerateDocumentationFile .

• Jeśli tworzysz aplikację przy użyciu programu Visual Studio, kliknij prawym przyciskiem myszy projekt i wybierz pozycję Właściwości. W oknie dialogowym właściwości wybierz kartę Kompilacja i zaznacz plik dokumentacji XML. Możesz również zmienić lokalizację, w której kompilator zapisuje plik.

Istnieją dwa sposoby pisania komentarzy dokumentacji XML: z tagami XML i bez tagów XML. Oba używają komentarzy z potrójnymi ukośnikami (///).

Komentarze bez tagów XML

Jeśli komentarz /// nie rozpoczyna się od <, cały tekst komentarza traktuje się jako podsumowującą dokumentację konstrukcji kodu, następującej bezpośrednio. Użyj tej metody, jeśli chcesz napisać tylko krótkie podsumowanie dla każdej konstrukcji.

Komentarz jest kodowany do kodu XML podczas przygotowywania dokumentacji, dlatego znaki takie jak <, >i & nie muszą być usuwane. Jeśli nie określisz jawnie tagu podsumowania, nie należy określać innych tagów, takich jak param lub zwraca tagi.

W poniższym przykładzie przedstawiono alternatywną metodę bez tagów XML. W tym przykładzie cały tekst w komentarzu jest traktowany jako podsumowanie.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

Komentarze z tagami XML

Jeśli treść komentarza zaczyna się od < (zwykle <summary>), jest ona traktowana jako treść komentarza sformatowanego w formacie XML przy użyciu tagów XML. Ten drugi sposób umożliwia określenie oddzielnych notatek dla krótkiego podsumowania, dodatkowych uwag, dokumentacji dla każdego zgłaszanego parametru i parametru typu oraz wyjątków oraz opisu wartości zwracanej.

Poniżej przedstawiono typowy komentarz dokumentacji XML w pliku podpisu:

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

Zalecane tagi

Jeśli używasz tagów XML, w poniższej tabeli opisano tagi zewnętrzne rozpoznane w komentarzach kodu XML języka F#.

Składnia tagów	Opis
<summary> tekst</summary>	Określa, że tekst jest krótkim opisem elementu programu. Opis jest zwykle jednym lub dwoma zdaniami.
<remarks> tekst</remarks>	Określa, że tekst zawiera dodatkowe informacje na temat elementu programu.
<param name=" nazwa">opis</param>	Określa nazwę i opis funkcji lub parametru metody.
<typeparam name=" nazwa">opis</typeparam>	Określa nazwę i opis parametru typu.
<returns> tekst</returns>	Określa, że tekst opisuje zwracaną wartość funkcji lub metody.
<exception cref=" typ">opis</exception>	Określa typ wyjątku, który można wygenerować, oraz okoliczności, w których jest zgłaszany.
<seealso cref=" odniesienie"/>	Określa link Zobacz również do dokumentacji dla innego typu. Nazwa odniesienia to taka, jaka pojawia się w pliku dokumentacji XML. Zobacz Również linki zwykle pojawiają się w dolnej części strony dokumentacji.

W poniższej tabeli opisano tagi do użycia w sekcjach opisu:

Składnia tagów	Opis
<para> tekst</para>	Określa akapit tekstu. Służy do oddzielania tekstu wewnątrz tagu uwagi.
<code> tekst</code>	Określa, że tekst to wiele wierszy kodu. Ten tag może być używany przez generatory dokumentacji do wyświetlania tekstu w czcionki, która jest odpowiednia dla kodu.
<paramref name=" nazwa"/>	Określa odwołanie do parametru w tym samym komentarzu dokumentacji.
<typeparamref name=" nazwa"/>	Określa odwołanie do parametru typu w tym samym komentarzu dokumentacji.
<c> tekst</c>	Określa, że tekst jest kodem w linii. Ten tag może być używany przez generatory dokumentacji do wyświetlania tekstu w czcionki, która jest odpowiednia dla kodu.
<see cref=" "> tekst</see>	Określa wbudowany link do innego elementu programu. Nazwa odniesienia to taka, jaka pojawia się w pliku dokumentacji XML. Tekst jest tekstem wyświetlanym w linku.

Tagi zdefiniowane przez użytkownika

Poprzednie tagi reprezentują te, które są rozpoznawane przez kompilator języka F# i typowe narzędzia edytora języka F#. Użytkownik może jednak definiować własne tagi. Narzędzia takie jak fsdocs obsługują dodatkowe tagi, takie jak <namespacedoc>. Niestandardowe lub wewnętrzne narzędzia do generowania dokumentacji mogą być również używane ze standardowymi tagami, a obsługiwane mogą być liczne formaty wyjściowe, od HTML po PDF.

Sprawdzanie czasu kompilacji

Po włączeniu --warnon:3390 kompilator weryfikuje składnię kodu XML oraz parametry określone w tagach <param> i <paramref>.

Dokumentowanie konstrukcji języka F#

W języku F# konstrukcje, takie jak moduły, członkowie, przypadki unii i pola rekordów, dokumentuje się za pomocą komentarza /// bezpośrednio przed ich deklaracją. W razie potrzeby konstruktory niejawne klas są udokumentowane przez dodanie komentarza /// przed listą argumentów. Na przykład:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Ograniczenia

Niektóre funkcje dokumentacji XML w języku C# i innych językach platformy .NET nie są obsługiwane w języku F#.

• W języku F# odwołania krzyżowe muszą używać pełnego podpisu XML odpowiedniego symbolu, na przykład cref="T:System.Console". Proste odwołania w stylu C#, takie jak cref="Console", nie są opracowywane dla pełnych podpisów XML i te elementy nie są sprawdzane przez kompilator języka F#. Niektóre narzędzia dokumentacyjne mogą zezwalać na wykorzystywanie tych odwołań krzyżowych w dalszym przetwarzaniu, ale należy używać pełnych sygnatur.

• Tagi <include>, <inheritdoc> nie są obsługiwane przez kompilator języka F#. Nie zostanie zgłoszony żaden błąd, jeśli są stosowane; są one po prostu kopiowane do wygenerowanego pliku dokumentacji bez wpływu na jego zawartość poza tym.

• Odwołania krzyżowe nie są sprawdzane przez kompilator języka F#, nawet jeśli jest używana -warnon:3390.

• Nazwy używane w tagach <typeparam> i <typeparamref> nie są sprawdzane przez kompilator języka F#, nawet w przypadku użycia --warnon:3390.

• Nie podano żadnych ostrzeżeń, jeśli brakuje dokumentacji, nawet jeśli jest używana --warnon:3390.

Zalecenia

Dokumentowanie kodu jest zalecane z wielu powodów. Poniżej przedstawiono kilka najlepszych rozwiązań, 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 F#.

• Włącz opcję --warnon:3390 w kodzie, aby upewnić się, że dokumentacja XML jest prawidłowa.

• Rozważ dodanie plików podpisów w celu oddzielenia długich komentarzy dokumentacji XML od implementacji.

• Ze względu na spójność wszystkie publicznie widoczne typy i ich składowe powinny być udokumentowane. Jeśli musisz to zrobić, zrób to wszystko.

• Na minimalnym poziomie moduły, typy i ich składowe powinny mieć zwykły komentarz /// lub tag <summary>. Wyświetli się to w okienku podpowiedzi autouzupełniania w narzędziach do edycji F#.

• Tekst dokumentacji powinien być napisany z użyciem pełnych zdań kończących się kropkami.

Zobacz też

• Komentarze XML do dokumentacji C# (Przewodnik programowania C#).
• Odniesienie do języka F#
• opcje kompilatora