Skip to content

Use block-level elements consistently #602

@sharwell

Description

@sharwell

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>

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions