Documente seu código com comentários XML

Artigo
12/17/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 o seu assembly .NET para que os IDEs possam usar notas de rodapé 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.

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

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

Você pode adicionar um elemento GenerateDocumentationFile à seção <PropertyGroup> do seu arquivo de projeto .fsproj, 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 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 de propriedades, selecione o separador Build e marque a opçã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á considerado 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 retorna 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 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 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 etiqueta	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 suplementares sobre o elemento do programa.
`<param name="` *nome`">`descrição*`</param>`	Especifica o nome e a descrição de uma função ou parâmetro de método.
`<typeparam name="` *nome`">`descrição*`</typeparam>`	Especifica o nome e a descrição de um parâmetro type.
`<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 gerada e as circunstâncias em que ela é lançada.
`<seealso cref="` *referência*`"/>`	Especifica um link de "Consulte também" para a documentação de outro tipo. A referência é o nome tal como aparece no ficheiro de documentação XML. Os links de "Consulte Também" 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 etiqueta	Descrição
`<para>` *texto*`</para>`	Especifica um parágrafo de texto. Isso é usado para separar o texto dentro da observações etiqueta.
`<code>` *texto*`</code>`	Especifica que o texto consiste em 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="` *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 de documentação.
`<c>` *texto*`</c>`	Especifica que texto é código inline. Essa tag pode ser usada por geradores de documentação para exibir texto em uma fonte apropriada para o código.
`<see cref="` *referência`">`texto*`</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 oferecem 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 referidos nas tags <param> e <paramref>.

Documentando construções de F#

Construções F#, como módulos, membros, casos de união e campos de registo, são documentadas com um comentário /// imediatamente antes da 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 é utilizado.

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 /// simples ou <summary> tag. Isso será mostrado numa janela de sugestão de preenchimento automático nas ferramentas de edição de F#.
O texto da documentação deve ser escrito usando frases completas que terminam com pontos finais.

Ver também

C# XML Documentation Comments (C# Programming Guide).
Referência da Linguagem F#
Opções do compilador

Partilhar via