SA1653: Only one partial declaration should contain summary documentation

Cause

More than one declaration of a partial type contains a top-level <summary> element.

Rule description

XML documentation from the declarations of a partial type is combined into documentation for a single type. Providing <summary> documentation on multiple declarations can result in duplicated or conflicting summaries.

Keep the official type documentation, including <summary> and any <typeparam> elements, on one declaration. Use <content> instead of <summary> to document the other parts for readers of the source code. This is consistent with SA1619.

The rule reports each declaration containing a conflicting summary, rather than choosing which declaration should retain it. It applies to existing documentation regardless of whether documentation is required for the type's accessibility. Summaries in generated declarations also contribute to conflicts, but diagnostics are only reported on non-generated declarations.

Only explicit, top-level <summary> elements are counted. Nested summaries and documentation supplied through <include> or <inheritdoc> are not expanded by this rule.

How to fix violations

Choose one declaration to retain the <summary> documentation, and change the other declarations to use <content>:

/// <summary>
/// Represents a request processor.
/// </summary>
public partial class RequestProcessor
{
}

/// <content>
/// Contains request validation logic.
/// </content>
public partial class RequestProcessor
{
}

No automatic code fix is provided, because choosing the primary declaration requires a user decision.

How to suppress violations

[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1653:OnlyOnePartialDeclarationShouldContainSummaryDocumentation", Justification = "Reviewed.")]

#pragma warning disable SA1653 // Only one partial declaration should contain summary documentation
#pragma warning restore SA1653 // Only one partial declaration should contain summary documentation