Table of Contents

SA1642: Constructor summary documentation should begin with standard text

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 record types, constructors follow the same pattern: record classes use the word 'class' in the summary text, while record structs use 'struct'. For example:

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

For C# 15 union types, the summary should contain the word 'union'. For example, the following shows the constructor for the Result<T> union.

public union Result<T>(T, string)
{
    /// <summary>
    /// Initializes a new instance of the <see cref="Result{T}"/> union.
    /// </summary>
    /// <param name="value">The value.</param>
    /// <param name="message">The message.</param>
    public Result(T value, string message)
    {
    }
}

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>
static Customer()
{
}

The standard text may also use <see langword="static"/>, <see langword="class"/>, or <see langword="struct"/> for the corresponding keyword. Record declarations may use <see langword="record"/> in place of their standard class or struct type kind. For example:

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

This allowance does not apply to words used as prose, such as new in the instance-constructor standard text.

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
Edit this page