C#: Documentação XML

 

Introdução

Ao utilizar um método nativo do C#, o ambiente de desenvolvimento exibe automaticamente uma descrição detalhada, informando sua funcionalidade, os parâmetros aceitos e o valor retornado. Isso facilita a compreensão e a reutilização do código. Por exemplo, podemos observar o método “Replace” da classe “String”, conforme a imagem abaixo.

Podemos observar que no momento da declaração do método a IDE exibe uma mensagem de “ajuda” explicando o tipo de retorno de método, quantidade de sobrecargas disponíveis e quais os parâmetros aceitos, esse é feito pelo IntelliSense.

O que é o IntelliSense

O IntelliSense é um conjunto de recursos de assistência ao código disponível em IDEs como Visual Studio, Rider e VS Code. Ele oferece sugestões inteligentes enquanto você digita, exibindo informações sobre métodos, classes e parâmetros, o que melhora a produtividade e reduz erros.

Utilizar comentários de documentação

Existe a possibilidade de aplicar essa configuração aos seus próprios métodos, o que é especialmente útil ao trabalhar em equipe, pois facilita a documentação e compreensão do código. Em um projeto com uma equipe de vários desenvolvedores, manter a documentação do código é fundamental para garantir clareza e colaboração.

Caso de Uso

Imagine que você precisa criar uma função que recebe uma string contendo texto entre parênteses e retorna apenas esse conteúdo entre parênteses. Embora seja uma função simples e utilizada apenas para fins didáticos, ela será chamada em vários pontos do projeto. Então você decide implementá-la em um “service”, e para isso criamos a classe “StringHelper” e o método “ExtrairTextoEntreParentese”.

Outros desenvolvedores utilizaram essa função, é importante documentá-la, explicando seu comportamento e a forma correta de uso. Uma maneira eficaz de fazer isso é utilizando comentários de documentação XML, que são reconhecidos pelo IntelliSense.

Vamos criar o método “ExtrairTextoEntreParentese”:

public static string ExtrairTextoEntreParenteses(string texto) 
{ 
	if (string.IsNullOrEmpty(texto))
    	{
    		return string.Empty;
        }
        
   	int posicaoInicial = texto.IndexOf('('); 
   	int posicaoFinal = texto.IndexOf(')'); 

	if (posicaoInicial == -1 || posicaoFinal == -1 || posicaoFinal < posicaoInicial)
    	{
    		return string.Empty;
        }
        
    	return texto.Substring(posicaoInicial + 1, posicaoFinal - posicaoInicial - 1); 
}

Então para documentar a função, antes da declaração da função vamos colocar os comentários XML, conforme abaixo:

/// <summary>Extrai o primeiro texto encontrado entre parênteses em uma string.</summary>
/// <param name="texto">A string de entrada que contém o texto entre parênteses.</param>
/// <returns>O conteúdo encontrado dentro dos primeiros parênteses, ou uma string vazia se não houver parênteses.</returns>
public static string ExtrairTextoEntreParenteses(string texto) 
{ 
	if (string.IsNullOrEmpty(texto))
    	{
    		return string.Empty;
        }
        
   	int posicaoInicial = texto.IndexOf('('); 
   	int posicaoFinal = texto.IndexOf(')'); 

	if (posicaoInicial == -1 || posicaoFinal == -1 || posicaoFinal < posicaoInicial)
    	{
    		return string.Empty;
        }
        
    	return texto.Substring(posicaoInicial + 1, posicaoFinal - posicaoInicial - 1); 
}

Esses comentários criam um resumo, explicando a função da função, o parâmetro que deve ser enviado e qual será o retorno. Quando alguém utilizar a função, o IntelliSense vai mostrar esse resumo conforme a imagem abaixo, o que é muito útil.

Pontos a considerar

O IntelliSense está integrado às principais IDEs, como Visual Studio, Rider e Visual Studio Code. Antes de utilizar os comentários de documentação XML, verifique se sua equipe trabalha com uma dessas ferramentas, pois elas oferecem suporte completo ao recurso.

Mais informações

Para mais informações sobre como funciona a documentação XML no C#, a Microsoft possui uma documentação muito boa sobre o tema, link documentação.