.NET 1.1+Adding Paragraph Breaks to XML Documentation
The readability of XML documentation, which is compiled into browsable HTML Help files, is greatly improved with the correct use of paragraphs. By using the para tag within other elements, descriptive information from the XML can include line breaks.
Paragraphs
When you are creating documentation for your code libraries you may need to create large amounts of content. If this is added to XML comments as plain text, it can end up being compiled into a HTML Help file and appearing as a solid block of information. This makes it harder to read so should be avoided. For example, consider the following basic class. Although there are line breaks in the summary comments for the class, these will not appear in the final help file. This is a good thing; if all line breaks signified new paragraphs, you would have to create very long lines in your comments to avoid them, making the comments themselves difficult to read.
/// <summary>
/// Utility class containing static methods that perform simple
/// but handy mathematical operations. All of the methods work
/// with decimal values and return decimal values. This gives
/// the greatest accuracy as single and double-precision
/// floating-point numbers are prone to rounding errors.
/// </summary>
public static class SimpleMathsUtilities
{
/// <summary>
/// Increases a value by a given percentage.
/// The percentage can be negative.
/// </summary>
/// <param name="value">The value to increase.</param>
/// <param name="percentage">The percentage.</param>
/// <returns>The new value</returns>
public static decimal AddPercentage(decimal value, decimal percentage)
{
return value * ((percentage / 100) + 1);
}
}Once the help file has been generated for the above class, using a tool such as Sandcastle Help File Builder, the text appears as a contiguous block. In the case of our example it isn't too bad because the text is reasonably short. For longer text the readability would suffer.
para Tag
When you wish to separate your documentation text into paragraphs you can use the para tag. This is added wherever you wish to start a new paragraph. It is included within other XML documentation elements and requires no attributes or inner text.
In the code below I've inserted a para tag within the summary text. It appears on the second line between the first and second sentences as the empty element tag, <para/>.
/// <summary>
/// Utility class containing static methods that perform simple
/// but handy mathematical operations.<para/>All of the methods work
/// with decimal values and return decimal values. This gives
/// the greatest accuracy as single and double-precision
/// floating-point numbers are prone to rounding errors.
/// </summary>
public static class SimpleMathsUtilities
{
/// <summary>
/// Increases a value by a given percentage.
/// The percentage can be negative.
/// </summary>
/// <param name="value">The value to increase.</param>
/// <param name="percentage">The percentage.</param>
/// <returns>The new value</returns>
public static decimal AddPercentage(decimal value, decimal percentage)
{
return value * ((percentage / 100) + 1);
}
}Once compiled, the text is correctly formatted with a new paragraph beginning where the para tag was encountered:
26 July 2012