SA1642.md

SA1642

TypeName	SA1642ConstructorSummaryDocumentationMustBeginWithStandardText
CheckId	SA1642
Category	Documentation Rules

Cause

The XML documentation header for a C# constructor does not contain the appropriate summary text.

Rule description

C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of XML documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments.

A violation of this rule occurs when the summary tag within the documentation header for a constructor does not begin with the proper text.

The rule is intended to standardize the summary text for a constructor based on the access level of the constructor. The summary for an instance constructor should begin with "Initializes a new instance of the {class name} class." For example, the following shows the constructor for the Customer class.

/// <summary>
/// Initializes a new instance of the <see cref="Customer"/> class.
/// </summary>
public Customer()
{
}

If documenting a struct, the summary should contain the word 'struct' instead of 'class'. For example, the following shows the constructor for the MyStruct struct.

/// <summary>
/// Initializes a new instance of the <see cref="MyStruct"/> struct.
/// </summary>
public MyStruct()
{
}

For C# 9 record types, constructors follow the same pattern: record classes use the word 'class' in the summary text, while record structs use 'struct'.

If the class contains generic parameters, these can be annotated within the cref link using either of the following two formats:

/// <summary>
/// Initializes a new instance of the <see cref="Customer`1"/> class.
/// </summary>
public Customer()
{
}

/// <summary>
/// Initializes a new instance of the <see cref="Customer{T}"/> class.
/// </summary>
public Customer()
{
}

If the constructor is static, the summary text should begin with "Initializes static members of the {class name} class." For example:

/// <summary>
/// Initializes static members of the <see cref="Customer"/> class.
/// </summary>
public static Customer()
{
}

For compatibility with StyleCop Classic, private instance constructors are allowed to use the summary text "Prevents a default instance of the {class name} class from being created." New code is encouraged to use the form above instead for all instance constructors.

/// <summary>
/// Prevents a default instance of the <see cref="Customer"/> class from being created.
/// </summary>
private Customer()
{
}

The <para> tag can be used within the <summary> tag to structure the text. For example:

/// <summary>
/// <para>
/// Initializes a new instance of the <see cref="Customer"/> class.
/// </para>
/// <para>
/// Additional information can be included in subsequent paragraphs.
/// </para>
/// </summary>
public Customer()
{
}

How to fix violations

To fix a violation of this rule, edit the summary text for the constructor as described above.

How to suppress violations

[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText", Justification = "Reviewed.")]

#pragma warning disable SA1642 // ConstructorSummaryDocumentationMustBeginWithStandardText
#pragma warning restore SA1642 // ConstructorSummaryDocumentationMustBeginWithStandardText