Documentação XML (F#)
Você pode produzir documentação do triple-barra (/ / /) comentários em F# de código.Comentários XML podem preceder 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 Sandcastle.A documentação gerada por meio de ferramentas projetadas para uso com assemblies que são escritos em outros.Idiomas do NET Framework geralmente produzem um modo de exibição das APIs com base na forma compilada de construções de F#.A menos que ferramentas especificamente suportam F#, documentação gerada por essas ferramentas não coincide com o modo de exibição F# de uma API.
Para obter mais informações sobre como gerar documentação XML, consulte Comentários de documentação XML (guia de programação do C#).
Marcas recomendadas
Existem duas formas de escrever comentários da documentação XML.Uma é simplesmente escrever a documentação diretamente em um comentário de triple-barra, sem usar as marcas XML.Se você fizer isso, o texto de comentário inteiro será interpretado como 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 documentação estruturada.O segundo método permite que você especifique notas separadas para um breve resumo, comentários adicionais, documentação para cada parâmetro e o parâmetro de tipo e exceções lançadas e uma descrição do que o 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 a texto é o código.Essa marca pode ser usada pelos geradores de documentação para exibir texto em uma fonte que seja apropriada para o código. |
<summary>texto</summary> |
Especifica que a texto é uma breve descrição do elemento de programa.A descrição é geralmente uma ou duas frases. |
<remarks>texto</remarks> |
Especifica que a texto contém informações complementares sobre o elemento de programa. |
<param name="name"> description</param> |
Especifica o nome e descrição para um parâmetro de função ou método. |
<typeparam name="name"> description </typeparam> |
Especifica o nome e descrição para um parâmetro de tipo. |
<returns>texto</returns> |
Especifica que a texto descreve o valor de retorno de uma função ou método. |
<exception cref="type">description</exception> |
Especifica o tipo de exceção que pode ser gerada e as circunstâncias sob as quais ela é lançada. |
<see cref="reference">text</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
.gif "Dd233217.collapse_all(pt-br,VS.110).gif")
Descrição
Este é 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