DOC201.md

DOC201

TypeName	DOC201ItemShouldHaveDescription
CheckId	DOC201
Category	Portability Rules

Cause

The documentation for an <item> within a <list> did not include the required <term> and/or <description> elements.

Rule description

According to the C# language specification, the <item> element within a documentation comment must have its content wrapped in a <description> element. Not all documentation processing tools support omitting the <description> element, so it should be included for consistent behavior.

/// <remarks>
/// <list type="bullet">
/// <item>This item has text not wrapped in a description element.</item>
/// </list>
/// </remarks>
public void SomeOperation()
{
}

See dotnet/csharplang#1765 for a language proposal to natively support lists with the <description> element removed.

How to fix violations

To fix a violation of this rule, wrap the content of the <item> element in a <description> element.

/// <remarks>
/// <list type="bullet">
/// <item><description>This item has text wrapped in a description element.</description></item>
/// </list>
/// </remarks>
public void SomeOperation()
{
}

How to suppress violations

This rule can be disabled rather than suppressed for projects whose documentation processing tools support <item> elements which are not wrapped in a <description> element. In other cases, the warning can be suppressed as follows:

#pragma warning disable DOC201 // Item should have description
/// <remarks>
/// <list type="bullet">
/// <item>This item has text not wrapped in a description element.</item>
/// </list>
/// </remarks>
public void SomeOperation()
#pragma warning restore DOC201 // Item should have description
{
}