Dokumentacja XML (F#)
Służy do tworzenia dokumentacji z triple ukośnik (/ / /) kod z uwagi na F#.Komentarze można poprzedzać deklaracje plików kodu (.fs) lub podpis (.fsi).
Generowanie dokumentacji z komentarzy
Obsługa F# generowania dokumentacji z komentarzy jest taka sama, jak w innych.NET Framework języków.W innych.NET Framework w językach, -doc opcję kompilatora umożliwia uzyskanie pliku XML, który zawiera informacje, które można przekonwertować na dokumentacji za pomocą narzędzia, takie jak Sandcastle.Dokumentację generowane przy użyciu narzędzia, które są zaprojektowane do użytku z zestawów, które zostały napisane w innych.NET Framework języków generalnie dają widok oparty na skompilowanej formie F# konstrukcjami interfejsów API.Chyba że narzędzia specjalnie obsługują F#, dokumentacji, generowane przez te narzędzia nie pasuje widok F# interfejs API.
Aby uzyskać więcej informacji o sposobach generowania dokumentacji z pliku XML, zobacz Komentarze dokumentacji XML (Przewodnik programowania w języku C#).
Zalecane znaczniki
Istnieją dwa sposoby pisania komentarzy dokumentacji XML.Jeden jest po prostu zapisać w dokumentacji bezpośrednio w polu Komentarz triple ukośnik, bez użycia tagów języka XML.Jeśli to zrobisz, cały tekst jest traktowana jako podsumowanie dokumentacji konstrukcji kodu, który następuje bezpośrednio.Tej metody należy użyć, gdy chcesz napisać krótkie podsumowanie dla konstrukcji.Inne metody jest bardziej structured dokumentację za pomocą tagów języka XML.Druga metoda umożliwia określenie oddzielnych notatki dla krótkie podsumowanie, dodatkowe uwagi, dokumentację dla każdego parametru i parametr typu i odrzucanych wyjątków i opis wartości zwracanej.W poniższej tabeli opisano tagów XML, które są rozpoznawane w komentarzy do kodu XML F#.
Składnia tag |
Opis |
|---|---|
<c>tekst</c> |
Określa, że tekst jest kod.Można tego tagu przez generatory dokumentacji do wyświetlania tekstu w czcionkę, która jest odpowiednia dla kodu. |
<summary>tekst</summary> |
Określa, że tekst znajduje się krótki opis elementu programu.Opis jest zazwyczaj jeden lub dwa zdania. |
<remarks>tekst</remarks> |
Określa, że tekst zawiera dodatkowe informacje dotyczące elementu programu. |
<param name="name"> description</param> |
Określa nazwę i opis dla parametru funkcji lub metody. |
<typeparam name="name"> description </typeparam> |
Określa nazwę i opis dla parametru typu. |
<returns>tekst</returns> |
Określa, że tekst w tym artykule opisano zwracana wartość funkcji lub metody. |
<exception cref="type">description</exception> |
Określa typ wyjątku, który może być generowane i okoliczności, w jakich jest generowane. |
<see cref="reference">text</see> |
Określa łącze wbudowane do innego elementu programu.Odniesienia jest nazwą wyświetlaną w polu Plik dokumentacji XML.Tekst jest tekst wyświetlany w łączu. |
<seealso cref="Odwołanie"/> |
Określa łącze Zobacz również dokumentację dla innego typu.Odniesienia jest nazwą wyświetlaną w polu Plik dokumentacji XML.Zobacz też łącza, które zwykle pojawiają się u dołu strony dokumentacji. |
<para>tekst</para> |
Określa akapit tekstu.To jest używany do oddzielania tekstu wewnątrz remarks tag. |
Przykład
Opis
Poniżej przedstawiono typowy komentarzy dokumentacji XML w pliku podpisu.
Kod
/// <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
Przykład
Opis
Poniższy przykład pokazuje alternatywne metody, bez znaczników XML.W tym przykładzie cały tekst w polu Komentarz jest uważany za podsumowanie.Uwaga, że jeśli nie określisz jawnie tag podsumowanie, nie należy określać inne znaczniki, takie jak param lub returns znaczniki.
Kod
/// 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