Na <returns>...</returns>seção de comentários da documentação dos meus métodos, gosto de fornecer detalhes específicos sobre o retorno dos métodos de tipo de dados.
Por exemplo, um método que retorna a Customer, meus comentários na documentação podem ser assim:
/// <summary>
/// Basic description/explanation of what this method does...
/// </summary>
/// <param name="id"></param>
/// <returns>Customer</returns>
public async Task<Customer> DoSomethingAsync(Guid id)
{
// Method logic
return myCustomer; // returning a Customer class
}
Isso funciona bem, mas se o método retornar, digamos, a List<Customer>e na returnsseção que eu uso <returns>List<Customer></returns>, recebo um aviso que diz:
O comentário XML possui um XML mal formado - 'Espera-se uma tag final para o elemento 'retorna'.'
Entendo que o Visual Studio está ficando confuso com o >in List<Customer>. Alguma sugestão de como ainda posso mostrar o que meus métodos retornam nesses casos ou simplesmente ignoro esses avisos?
A documentação aborda esse problema, dizendo:
Pessoalmente, eu usaria colchetes nas entidades XML, é muito mais fácil de ler dessa forma e também mais fácil de digitar.