Documentar o código com comentários XML

  • Artigo

Você pode produzir documentação a partir de comentários de código de barra tripla (///) no F#. Comentários XML podem preceder declarações em arquivos de código (.fs) ou arquivos de assinatura (.fsi).

Comentários em documentação XML são um tipo especial de comentário, adicionados acima da definição de qualquer membro ou tipo definido pelo usuário. Eles são especiais porque podem ser processados pelo compilador para gerar um arquivo de documentação XML em tempo de compilação. O arquivo XML gerado pelo compilador pode ser distribuído em conjunto com seu assembly .NET para que os IDEs possam usar dicas de ferramentas para mostrar informações rápidas sobre os tipos ou membros. Além disso, o arquivo XML pode ser executado por ferramentas como fsdocs para gerar sites de referência de API.

Os comentários da documentação XML, como todos os outros comentários, são ignorados pelo compilador, a menos que as opções descritas abaixo estejam habilitadas para verificar a validade e integridade dos comentários no momento da compilação.

É possível gerar o arquivo XML em tempo de compilação seguindo um destes procedimentos:

  • Você pode adicionar um elemento GenerateDocumentationFile à seção <PropertyGroup> do arquivo de projeto .fsproj, que gera um arquivo XML no diretório do projeto com o mesmo nome de arquivo raiz que o assembly. Por exemplo:

    <GenerateDocumentationFile>true</GenerateDocumentationFile>

    Para obter mais informações, confira propriedade GenerateDocumentationFile.

  • Se estiver desenvolvendo um aplicativo usando o Visual Studio, clique com botão direito do mouse no projeto e selecione Propriedades. Na caixa de diálogo Propriedades, selecione a guia Build e marque Arquivo de documentação XML. Também é possível alterar o local em que o compilador grava o arquivo.

Há duas maneiras de escrever comentários de documentação XML: com e sem marcas XML. Ambos usam comentários de barra tripla.

Comentários sem marcas XML

Se um comentário /// não começar com um <, todo o texto do comentário será obtido como a documentação resumida do constructo de código que se segue imediatamente. Use esse método quando quiser escrever apenas um breve resumo para cada constructo.

Como o comentário é codificado para XML durante a preparação da documentação, caracteres como <, > e & não precisam receber caracteres de escape. Se você não especificar explicitamente uma marca de resumo, não deverá especificar outras marcas, como param ou returns.

O exemplo a seguir mostra o método alternativo, sem marcas XML. Neste exemplo, todo o texto no comentário é considerado um resumo.

/// 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

Comentários com marcas XML

Se um corpo de comentário começar com < (normalmente <summary>), ele será tratado como um corpo de comentário formatado XML usando marcas XML. Essa segunda maneira permite que você especifique anotações separadas, como um breve resumo, comentários adicionais, documentação para cada parâmetro, parâmetro de tipo e exceções geradas, além de uma descrição do valor retornado.

Veja a seguir um comentário típico da documentação XML em um arquivo de assinatura:

/// <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

Se você estiver usando marcas XML, a tabela a seguir descreverá as marcas externas reconhecidas em comentários de código XML F#.

Sintaxe de marca Descrição
<summary>texto</summary> Especifica que texto é uma breve descrição do elemento do programa. A descrição geralmente tem uma ou duas frases.
<remarks>texto</remarks> Especifica que texto contém informações complementares sobre o elemento do programa.
<param name="nome">descrição</param> Especifica o nome e a descrição de um parâmetro de método ou função.
<typeparam name="nome">descrição</typeparam> Especifica o nome e a descrição de 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">descrição</exception> Especifica o tipo de exceção que pode ser gerado e as circunstâncias sob as quais ele é gerado.
<seealso cref="referência"/> Especifica um link "Confira também" para a documentação de outro tipo. A referência é o nome exibido no arquivo de documentação XML. Os links "Confira também" geralmente aparecem na parte inferior de uma página de documentação.

A tabela a seguir descreve as marcas para uso dentro das seções de descrição:

Sintaxe de marca Descrição
<para>texto</para> Especifica um parágrafo de texto. Isso é usado para separar textos dentro da marca de comentários.
<code>texto</code> Especifica que o texto tem várias linhas de código. Essa marca pode ser usada por geradores de documentação para exibir texto em uma fonte apropriada para código.
<paramref name="nome"/> Especifica uma referência a um parâmetro no mesmo comentário da documentação.
<typeparamref name="nome"/> Especifica uma referência a um parâmetro de tipo no mesmo comentário da documentação.
<c>texto</c> Especifica que texto é um código embutido. Essa marca pode ser usada por geradores de documentação para exibir texto em uma fonte apropriada para código.
<see cref="referência">texto</see> Especifica um link embutido para outro elemento de programa. A referência é o nome exibido no arquivo de documentação XML. O texto é o texto mostrado no link.

Marcas definidas pelo usuário

As marcas anteriores representam aquelas reconhecidas pelo compilador F# e pelas ferramentas típicas do editor F#. No entanto, o usuário é livre para definir suas próprias marcas. Ferramentas como fsdocs trazem suporte para marcas extras, como <namespacedoc>. Ferramentas de geração de documentação internas ou personalizadas também podem ser usadas com as marcas padrão e vários formatos de saída, de HTML a PDF, podem ter suporte.

Verificação de tempo de compilação

Quando --warnon:3390 estiver habilitado, o compilador verificará a sintaxe do XML e os parâmetros mencionados nas marcas <param> e <paramref>.

Documentação de constructos de F#

Os constructos de F#, como módulos, membros, casos de união e campos de registro, são documentados por um comentário /// imediatamente antes de sua declaração. Se necessário, os construtores implícitos de classes são documentados fazendo um comentário /// antes da lista de argumentos. Por exemplo:

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

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

Limitações

Alguns recursos da documentação XML em C# e outras linguagens .NET não têm suporte no F#.

  • Em F#, as referências cruzadas devem usar a assinatura XML completa do símbolo correspondente, por exemplo cref="T:System.Console". Referências cruzadas simples no estilo C#, como cref="Console" não são elaboradas para assinaturas XML completas, e esses elementos não são verificados pelo compilador F#. Algumas ferramentas de documentação podem permitir o uso dessas referências cruzadas pelo processamento subsequente, mas as assinaturas completas devem ser usadas.

  • As marcas <include><inheritdoc> não são compatíveis com o compilador F#. Nenhum erro será dado se eles forem usados, mas eles serão simplesmente copiados para o arquivo de documentação gerado, sem afetar de outra forma a documentação gerada.

  • As referências cruzadas não são verificadas pelo compilador F#, mesmo quando -warnon:3390 é usado.

  • Os nomes usados nas marcas <typeparam> e <typeparamref> não são verificados pelo compilador F#, mesmo quando --warnon:3390 é usado.

  • Nenhum aviso será dado se a documentação estiver ausente, mesmo quando --warnon:3390 for usado.

Recomendações

Documentar o código é recomendável por vários motivos. A seguir, temos algumas práticas recomendadas, cenários de caso de uso gerais e coisas que você precisa saber ao usar marcas de documentação XML em seu código F#.

  • Habilite a opção --warnon:3390 em seu código para ajudar a garantir que sua documentação XML seja um XML válido.

  • Considere adicionar arquivos de assinatura para separar comentários de documentação XML longos da sua implementação.

  • Para fins de consistência, todos os tipos visíveis publicamente e seus membros devem ser documentados. Se você precisar fazer isso, faça tudo.

  • No mínimo, módulos, tipos e seus membros devem ter um comentário /// ou marca <summary> simples. Isso será mostrado em uma janela de dica de ferramenta de preenchimento automático nas ferramentas de edição do F#.

  • O texto da documentação deve ser escrito usando frases terminadas com ponto final.

Confira também