visual-studio

Returns tag in documentation comments in Visual Studio

In the <returns>...</returns> section of documentation comments of my methods, I like providing specifics of data type methods return.

For example, a method that returns a Customer, my documentation comments may look like this:

/// <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
}

This works fine but if the method returns, say, a List<Customer> and in the returns section, I use <returns>List<Customer></returns>, I get a warning that reads:

XML comment has badly formed XML -- 'Expected an end tag for element 'returns'.'

I get that Visual Studio is getting confused with the > in List<Customer>. Any suggestions how I can still show what my methods return in such cases or do I simply ignore these warnings?

Solution

  • The documentation addresses this issue, saying:

    For code elements that are generic, the normal generic syntax (e.g., “List<T>”) cannot be used because it produces invalid XML. Braces can be used instead of brackets (e.g.; “List{T}”), or the XML escape syntax can be used (e.g., “List&lt;T&gt;”).

    Personally, I would go with the braces over the XML entities, it's much easier to read that way, and also easier to type.