Documente seu código com comentários XML

Artigo
03/02/2024

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

Comentários de 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. 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 junto com seu assembly .NET para que os IDEs possam usar dicas de ferramentas para mostrar informações rápidas sobre tipos ou membros. Além disso, o arquivo XML pode ser executado através de ferramentas como fsdocs para gerar sites de referência de API.

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 em tempo de compilação.

Você pode gerar o arquivo XML em tempo de compilação seguindo um destes procedimentos:

Você pode adicionar um GenerateDocumentationFile elemento à <PropertyGroup> seção do arquivo .fsproj de projeto, que gera um arquivo XML no diretório do projeto com o mesmo nome de arquivo raiz do assembly. Por exemplo:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Para obter mais informações, consulte GenerateDocumentationFile propriedade.
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 de propriedades, selecione a guia Construir e verifique o 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á tomado como a documentação de resumo para a construção de código que se segue imediatamente. Use esse método quando quiser escrever apenas um breve resumo para cada construção.

O comentário é codificado em XML durante a preparação da documentação, portanto, caracteres como <, >e & não precisam ser escapados. Se você não especificar uma tag de resumo explicitamente, não deverá especificar outras tags, como param ou returns tags.

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 em XML usando marcas XML. Essa segunda maneira permite especificar notas separadas para um breve resumo, observações adicionais, documentação para cada parâmetro e parâmetro de tipo e exceções lançadas, e uma descrição do valor de retorno.

A seguir está 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

Tags recomendadas

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

Sintaxe da tag	Description
`<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 suplementares sobre o elemento do programa.
`<param name="`*Descrição do nome*`"></param>`	Especifica o nome e a descrição de uma função ou parâmetro de método.
`<typeparam name="`*Descrição do nome*`"></typeparam>`	Especifica o nome e a descrição de um parâmetro type.
`<returns>`*texto*`</returns>`	Especifica que o texto descreve o valor de retorno de uma função ou método.
`<exception cref="`*descrição do tipo*`"></exception>`	Especifica o tipo de exceção que pode ser gerada e as circunstâncias em que ela é lançada.
`<seealso cref="`*referência*`"/>`	Especifica um link Consulte também para a documentação de outro tipo. A referência é o nome tal como aparece no ficheiro de documentação XML. Consulte Também os links geralmente aparecem na parte inferior de uma página de documentação.

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

Sintaxe da tag	Description
`<para>`*texto*`</para>`	Especifica um parágrafo de texto. Isso é usado para separar o texto dentro da tag de comentários .
`<code>`*texto*`</code>`	Especifica que o texto é várias linhas de código. Essa tag pode ser usada por geradores de documentação para exibir texto em uma fonte apropriada para o código.
`<paramref name="`*Designação*`"/>`	Especifica uma referência a um parâmetro no mesmo comentário da documentação.
`<typeparamref name="`*Designação*`"/>`	Especifica uma referência a um parâmetro type no mesmo comentário da documentação.
`<c>`*texto*`</c>`	Especifica que o texto é código embutido. Essa tag pode ser usada por geradores de documentação para exibir texto em uma fonte apropriada para o código.
`<see cref="`*texto de referência*`"></see>`	Especifica um link embutido para outro elemento do programa. A referência é o nome tal como aparece no ficheiro de documentação XML. O texto é o texto mostrado no link.

Tags definidas pelo usuário

As tags anteriores representam aquelas que são reconhecidas pelo compilador F# e pelas ferramentas típicas do editor F#. No entanto, um usuário é livre para definir suas próprias tags. Ferramentas como fsdocs trazem suporte para tags 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 de HTML para PDF podem ser suportados.

Verificação em tempo de compilação

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

Documentando construções de F#

Construções F# como módulos, membros, casos de união e campos de registro são documentadas por um /// comentário imediatamente antes de sua declaração. Se necessário, os construtores implícitos de classes são documentados dando 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 são suportados em 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 por processamento subsequente, mas as assinaturas completas devem ser usadas.
As tags <include>, <inheritdoc> não são suportadas pelo compilador F#. Nenhum erro é dado se eles forem usados, mas eles são simplesmente copiados para o arquivo de documentação gerado sem afetar 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 tags <typeparam> e <typeparamref> não são verificados pelo compilador F#, mesmo quando --warnon:3390 é usado.
Não são dados avisos se a documentação estiver em falta, mesmo quando --warnon:3390 é utilizada.

Recomendações

Documentar o código é recomendado por muitos motivos. A seguir estão algumas práticas recomendadas, cenários gerais de casos 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 da sua implementação.
Por razões de coerência, todos os tipos publicamente visíveis e os seus membros devem ser documentados. Se tiver de o fazer, faça tudo.
No mínimo, módulos, tipos e seus membros devem ter um comentário ou <summary> tag simples///. Isso será exibido em uma janela de dica de ferramenta de preenchimento automático nas ferramentas de edição F#.
O texto da documentação deve ser escrito usando frases completas que terminam com pontos finais.

Partilhar via