Dokumentowanie kodu z komentarzami XML

Artykuł
03/05/2024

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, dzięki czemu środowiska IDE mogą używać etykietek narzędzi do wyświetlania szybkich informacji o typach lub elementach członkowskich. Ponadto plik XML można uruchamiać za pomocą narzędzi, takich jak fsdocs , aby wygenerować witryny internetowe referencyjne interfejsu API.

Komentarze dokumentacji XML, podobnie jak wszystkie inne komentarze, są ignorowane przez kompilator, chyba że opcje opisane poniżej są włączone do sprawdzania poprawności i kompletności komentarzy w czasie kompilacji.

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

Element można dodać GenerateDocumentationFile do <PropertyGroup> sekcji .fsproj pliku projektu, 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 polecenie Właściwości. W oknie dialogowym właściwości wybierz kartę Kompilacja i sprawdź 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 potrójnego ukośnika.

Komentarze bez tagów XML

/// Jeśli komentarz nie zaczyna się od <, cały tekst komentarza jest traktowany jako dokumentacja podsumowania konstrukcji kodu, która natychmiast następuje. Użyj tej metody, jeśli chcesz napisać tylko krótkie podsumowanie dla każdej konstrukcji.

Komentarz jest zakodowany w formacie XML podczas przygotowywania dokumentacji, więc znaki takie jak <, >i & nie muszą być ucieczki. 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 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>`*text*`</summary>`	Określa, że tekst jest krótkim opisem elementu programu. Opis jest zwykle jednym lub dwoma zdaniami.
`<remarks>`*text*`</remarks>`	Określa, że tekst zawiera dodatkowe informacje dotyczące elementu programu.
`<param name="`*opis nazwy*`"></param>`	Określa nazwę i opis funkcji lub parametru metody.
`<typeparam name="`*opis nazwy*`"></typeparam>`	Określa nazwę i opis parametru typu.
`<returns>`*text*`</returns>`	Określa, że tekst opisuje zwracaną wartość funkcji lub metody.
`<exception cref="`*opis typu*`"></exception>`	Określa typ wyjątku, który można wygenerować, oraz okoliczności, w których jest zgłaszany.
`<seealso cref="`*Odwołanie*`"/>`	Określa link Zobacz również do dokumentacji dla innego typu. Odwołanie to nazwa wyświetlana 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>`*text*`</para>`	Określa akapit tekstu. Służy do oddzielania tekstu wewnątrz tagu uwagi .
`<code>`*text*`</code>`	Określa, że tekst jest wieloma wierszami 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="`*name*`"/>`	Określa odwołanie do parametru w tym samym komentarzu dokumentacji.
`<typeparamref name="`*name*`"/>`	Określa odwołanie do parametru typu w tym samym komentarzu dokumentacji.
`<c>`*text*`</c>`	Określa, że tekst jest wbudowanym kodem. 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 odwołania*`"></see>`	Określa wbudowany link do innego elementu programu. Odwołanie to nazwa wyświetlana 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 i wieloma formatami danych wyjściowych z kodu HTML do formatu PDF.

Sprawdzanie czasu kompilacji

Po --warnon:3390 włączeniu kompilator weryfikuje składnię kodu XML i parametry, o których mowa w pliku <param> i <paramref> tagi.

Dokumentowanie konstrukcji języka F#

Konstrukcje języka F#, takie jak moduły, elementy członkowskie, sprawy unii i pola rekordów, są udokumentowane przez komentarz bezpośrednio przed ich deklaracją /// . W razie potrzeby konstruktory niejawne klas są udokumentowane, podając komentarz 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 do pełnych podpisów XML, a te elementy nie są sprawdzane przez kompilator języka F#. Niektóre narzędzia dokumentacji mogą zezwalać na korzystanie z tych odwołań krzyżowych przez kolejne przetwarzanie, ale należy użyć pełnych podpisów.
Tagi <include>nie <inheritdoc> są obsługiwane przez kompilator języka F#. Nie podano żadnego błędu, jeśli są używane, ale są po prostu kopiowane do wygenerowanego pliku dokumentacji bez wpływu na wygenerowaną dokumentację.
Odwołania krzyżowe nie są sprawdzane przez kompilator języka F#, nawet jeśli -warnon:3390 jest używany.
Nazwy używane w tagach <typeparam> i <typeparamref> nie są sprawdzane przez kompilator języka F#, nawet jeśli --warnon:3390 jest używany.
Nie podano żadnych ostrzeżeń, jeśli brakuje dokumentacji, nawet jeśli --warnon:3390 jest używana.

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 członkowie powinni mieć zwykły /// komentarz lub <summary> tag. Spowoduje to wyświetlenie w oknie etykietki narzędzia autouzupełniania w narzędziach do edycji języka F#.
Tekst dokumentacji powinien być napisany przy użyciu pełnych zdań kończących się pełnymi zatrzymaniami.