Compartilhar via

Documentar seu código com comentários XML

  • Artigo

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

Os comentários da documentação XML são um tipo especial de comentário, adicionado acima da definição de qualquer tipo ou membro definido pelo usuário. Elas são especiais porque podem ser processadas pelo compilador para gerar um arquivo de documentação XML no momento da 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 meio de ferramentas como fsdocs para gerar sites de referência de API.

Por padrão, os comentários da documentação XML são ignorados pelo compilador. Para alterar isso, defina --warnon:3390. Em seguida, o compilador verificará a sintaxe do XML e os parâmetros referenciados em marcas <param> e <paramref>.

Você pode gerar o arquivo XML em tempo de compilação fazendo um dos seguintes 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, consulte a propriedade GenerateDocumentationFile.

  • Se você estiver desenvolvendo um aplicativo usando o Visual Studio, clique com o 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. Você também pode alterar o local no qual 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á usado 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 tags XML

Se um corpo de comentário começar com < (normalmente <summary>), ele será tratado como um corpo de comentário formatado em XML usando marcas XML. Essa segunda maneira permite que você especifique anotações separadas para um breve resumo, comentários adicionais, documentação para cada parâmetro e parâmetro de tipo e exceções geradas e 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 o texto é uma breve descrição do elemento do programa. A descrição geralmente é uma ou duas frases.
<remarks> texto</remarks> Especifica que o 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 função ou método.
<typeparam name="nome">descrição</typeparam> Especifica o nome e a descrição de um parâmetro de tipo.
<returns> texto</returns> Especifica que o texto descreve o valor retornado de uma função ou método.
<exception cref=" tipo">descrição</exception> Especifica o tipo de exceção que pode ser gerada e as circunstâncias sob as quais ela é gerada.
<seealso cref=" referência"/> Especifica um link de "Consulte também" para a documentação de outro tipo. A referência é o nome exibido no arquivo de documentação XML. Links do Veja 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 consiste em 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 de documentação.
<typeparamref name=" nome"/> Especifica uma referência a um parâmetro de tipo no mesmo comentário de 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 oferecem suporte para marcas extras, como <namespacedoc>. Ferramentas de geração de documentação personalizadas ou internas também podem ser usadas com as tags padrão, e vários formatos de saída, desde HTML até PDF, podem ser suportados.

Verificação de tempo de compilação

Quando --warnon:3390 está habilitado, o compilador verifica a sintaxe do XML e os parâmetros referenciados em marcas <param> e <paramref>.

Documentando constructos F#

Os constructos 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, construtores implícitos de classes são documentados fornecendo 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

Não há suporte para alguns recursos da documentação XML em C# e em outros idiomas do .NET 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 em 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 sã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

O código de documentação é recomendado por muitos motivos. O que se segue são algumas práticas recomendadas, cenários gerais de caso de uso e coisas que você deve 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 XML válida.

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

  • Para fins de consistência, todos os tipos publicamente visíveis e seus membros devem ser documentados. Se você precisa 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 completas que terminam com paradas completas.

Consulte também