Multiple summary tags supported when using primary constructors/records

[Thomas-Shephard]

Multiple summary tags supported when using primary constructors/records

Summary

Summary tags are part of the documentation comments feature in C# and are used by tools like IntelliSense to display information about a type or method. They are also used by automated documentation tools like Doxygen to extract information.

With primary constructors, classes and structs can have a parameter list with these parameters being scoped to the type. The same also applies to records.

/// <summary>
/// This is the class
/// </summary>
public class File
{
    private string _filePath;

    /// <summary>
    /// This is the constructor
    /// </summary>
    public File(string filePath)
    {
        _filePath = filePath;
    }
}

/// <summary>
/// This is both the class and the constructor
/// </summary>
public class File(string filePath)
{

}

This means that a summary tag when using a primary constructor describes both the constructor and the type. This has the possibility to cause confusion when using IntelliSense or another tool like Doxygen.

Current Visual Studio Behaviour

Screenshots taken of the current behaviour within Visual Studio 2022 (17.11.5).

Proposal

To have multiple summary tags on a primary constructor with an attribute specifying whether the summary tag is for the type or the constructor. This would allow the summary tags to be just as useful when using a primary constructor and not require developers to need to use the more verbose style to achieve full documentation.

/// <summary for="type">
/// This is the class
/// </summary>
/// <summary for="ctor">
/// This is the constructor
/// </summary>
public class FileWithPrimaryConstructor(string filePath)
{

}