-
Notifications
You must be signed in to change notification settings - Fork 513
Description
I would like to propose the implementation and inclusion of a new StyleCop diagnostic.
Category: Documentation
Rule: Use block-level elements consistently
Description: If any element of the XML documentation contains a block-level element as a child, then all immediate children of the element should be block-level elements. This generally applies to elements containing multiple paragraphs (the <para>
block-level element), but can also be affected by elements like <list>
and <note>
.
Note: This is an expansion of #601.
Rationale: This rule ensures these elements appear consistently when rendered to a variety of output media, including HTML.
Example: The most common violation of this rule in my own documentation of the past is the following:
/// <exception cref="ArgumentNullException">
/// If <paramref name="x"/> is <see langword="null"/>.
/// <para>-or-</para>
/// <para>If <paramref name="y"/> is <see langword="null"/>.</para>
/// </exception>
Since the <exception>
element contained at least one <para>
element as a child, the first sentence should also have been written within a <para>
element:
/// <exception cref="ArgumentNullException">
/// <para>If <paramref name="x"/> is <see langword="null"/>.</para>
/// <para>-or-</para>
/// <para>If <paramref name="y"/> is <see langword="null"/>.</para>
/// </exception>