Documentação XML (F#)
Você pode produzir documentação do triple-barra (/ / /) comentários em F# de código. Comentários XML podem preceder as declarações em arquivos de código (.fs) ou arquivos de assinatura (.fsi).
Gerando documentação de comentários
O suporte no F# para gerar a documentação de comentários é o mesmo que em outros.Idiomas do NET Framework. Como em outros.Idiomas do NET Framework, o -opção de compilador do doc lhe permite produzir um arquivo XML que contém informações que você pode converter em documentação usando uma ferramenta como, por exemplo, Sandcastle. A documentação gerada usando ferramentas projetadas para uso com os assemblies que são escritos em outros.Idiomas do NET Framework geralmente produzem um modo de exibição das APIs que baseia-se a forma compilada da F# construções. A menos que ferramentas especificamente suportam F#, documentação, gerada por essas ferramentas não corresponde a exibição de uma API F#.
Para obter mais informações sobre como gerar documentação XML, consulte Comentários de documentação XML (Guia de programação C#).
Marcas recomendadas
Há duas maneiras de se escrever comentários de documentação XML. Uma é simplesmente escrever a documentação diretamente em um comentário de barra triplo, sem usar marcas XML. Se você fizer isso, o texto de comentário inteiro é considerado a documentação de resumo para a construção de código que segue imediatamente. Use esse método quando você deseja escrever um breve resumo para cada construção. O outro método é usar as marcas XML para fornecer mais estruturada documentação. O segundo método permite que você especifique notas separadas para um breve resumo, comentários adicionais, documentação para cada parâmetro, parâmetro de tipo e exceções lançadas e uma descrição do valor de retorno. A tabela a seguir descreve as marcas XML que são reconhecidas nos comentários do código de F#. XML.
Sintaxe de marca |
Descrição |
|---|---|
<c> texto </c> |
Especifica que texto é o código. Essa marca pode ser usada pelos geradores de documentação para exibir texto em uma fonte que é apropriada para o código. |
<summary> texto </summary> |
Especifica que texto é uma breve descrição do elemento de programa. A descrição é normalmente uma ou duas frases. |
<remarks> texto </remarks> |
Especifica que texto contém informações complementares sobre o elemento de programa. |
<param name="nome"> descrição </param> |
Especifica o nome e descrição para um parâmetro de função ou método. |
<typeparam name="nome"> descrição </typeparam> |
Especifica o nome e descrição para um parâmetro de tipo. |
<returns> texto </returns> |
Especifica que texto descreve o valor de retorno de uma função ou método. |
<exception cref="tipo de"> Descrição </exception> |
Especifica o tipo de exceção pode ser gerada e as circunstâncias sob as quais é lançada. |
<see cref="referência"> texto </see> |
Especifica um link incorporado a outro elemento de programa. O referência é o nome que aparece no arquivo de documentação XML. O texto é o texto mostrado no link. |
<seealso cref="referência"/> |
Especifica um link Consulte também a documentação para outro tipo. O referência é o nome que aparece no arquivo de documentação XML. Consulte também normalmente aparecem na parte inferior de uma página de documentação de links. |
<para> texto </para> |
Especifica um parágrafo de texto. Isso é usado para separar o texto dentro do remarks marca. |
Exemplo
Descrição
A seguir é um comentário de documentação XML típico em um arquivo de assinatura.
Código
/// <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
Exemplo
Descrição
O exemplo a seguir mostra o método alternativo, sem marcas de formatação XML. Neste exemplo, todo o texto do comentário é considerado um resumo. Observe que se você não especificar explicitamente uma marca de resumo, você deve especificar outras marcas, como param ou returns marcas.
Código
/// 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