Creating a New Line in Visual Studio Documentation
I am writing documentation about a function in Visual Studio 2017. At some point, I need a new line symbol in order to obtain more smooth style of the documentation. The example situation is presented below:
public interface IPersonService : IDisposable
{
/// <summary>
/// Procedure that returns a list of people with the given first and last name.
///
/// <para>
/// First and last names are not case sensitive. ('friedrich schiller' == 'fRieDrich scHIller')
/// </para>
/// <example>
/// The following example returns a list of people with the first name 'friedrich' and the last name 'schiller': (newline should come here)
/// <code>
/// IList <Person> personList = _personService.GetList("friedrich","schiller");
/// </code>
/// </example>
/// </summary>
/// <param name="name">Name of the person being called. It cannot be null. It is not case sensitive.</param>
/// <param name="surname">Surname of the person being called. It cannot be null. It is not case sensitive.</param>
/// <returns>
/// IList- Person, List of people with name and surname,
/// list with 0 elements- If there is no person with your name and surname.
/// </returns>
IList<Person> GetList(string name, string surname);
}
I read the "Recommended XML tags for C# documentation comments" but cannot find it. "\n" does not work. Do you know how I can solve this? Thanks in advance.
I would use the standard <para> tag as much as possible. In your case, I would simply do it as follows:
/// <para>
/// The following example returns a list of people with the first name 'friedrich' and the last name 'schiller': (newline should come here)
/// <para>
But anyway, to enter a newline, use the <br/> tag. It is recognized by IntelliSense in VS and by the documentation tools as well (for example our VSdocman).
UPDATE for VS 2017
I just realized that you are using an old VS 2017. IntelliSense is not that good there. There's no newline displayed. With the current VS 2022, everything is OK, even without the <br/>, because the <code> tag is always rendered on a newline:
And of course, the <br/> works fine in VS 2022 as well. To conclude, in VS 2017, you get the correct newlines only in a generated documentation. In IntelliSense, you will not. You should update to VS 2022.
Moreover, your use of the <example> tag is wrong. It's a top-level tag, and it should not be nested in another tag, such as <summary> in your case. It is intended to create a separate section in the generated documentation. This is an example.
The correct comment should be:
/// <summary>
/// Procedure that returns a list of people with the given first and last name.
///
/// <para>
/// First and last names are not case sensitive. ('friedrich schiller' == 'fRieDrich scHIller')
/// </para>
/// </summary>
/// <param name="name">Name of the person being called. It cannot be null. It is not case sensitive.</param>
/// <param name="surname">Surname of the person being called. It cannot be null. It is not case sensitive.</param>
/// <returns>
/// IList- Person, List of people with name and surname,
/// list with 0 elements- If there is no person with your name and surname.
/// </returns>
/// <example>
/// The following example returns a list of people with the first name 'friedrich' and the last name 'schiller': (newline should come here)
/// <code>
/// IList <Person> personList = _personService.GetList("friedrich","schiller");
/// </code>
/// </example>
However, keep in mind that IntelliSense in VS 2017 only displays the contents of the <summary> tag. It ignores <example> and <remarks>. In VS 2022 it's much better, the <remarks> is displayed, but the <example> is still ignored. So in VS 2022, you can put your examples inside a <remarks> tag instead of the <example> to make them available in IntelliSense.