Need to add new XML documentation tag to support C# primary constructors

[vsfeedback]

This issue has been moved from a ticket on Developer Community.

---

Primary constructors were added in C# 12, and they are wonderful! Unfortunately, they cause ambiguity when adding <summary> tags to classes that use them (see XML documentation).

Currently, <summary> documentation applied to classes with primary constructors are used by Visual Studio/Code IntelliSense as both the class documentation and the constructor documentation. To disambiguate these, we need a new tag.

I propose adding a <constructor> tag. When applied to classes with primary constructors, the <constructor> tag would be used as if it were the <summary> tag of the constructor. The <summary> tag would continue to be for the class documentation.

For example:

/// <summary>
/// This would continue to be the documentation for the class.
/// </summary>
/// <constructor>
/// This would be the documentation for the class's primary constructor.
/// </constructor>
/// <param name="x">This would continue to document the constructor parameter x.</param>
public class MyClass(int x)
{
}

---

Original Comments

Feedback Bot on 2/26/2025, 02:50 AM:

We have directed your feedback to the appropriate engineering team for further evaluation. The team will review the feedback and notify you about the next steps.

[jjonescz]

Similar issue: dotnet/roslyn#75272

[DaRosenberg]

I think something more robust is needed. What about remarks, for example? Choosing the summary tag as the only one that can be provided for a primary constructor seems a bit half-baked and arbitrary. For parameters and return values, I guess it works because they can only reasonably apply to the constructor, but it feels coincidental and lacks clarity IMO.

Since we are dealing with XML, how about actually using it fully? Maybe something like this?

/// <summary>Summary for class MyClass.</summary>
/// <ctor>
///   <summary>Summary for primary constructor.</summary>
///   <param name="x">Description for constructor parameter x.</param>
///   <remarks>
///   Remarks for primary constructor.
///   </remarks>
/// </ctor>
public class MyClass(int x)
{
}

[zms9110750]

i want i18n to xml

[mikernet]

I love primary ctors but this is a big issue for being able to document libs properly. Would love to see any kind of solution here.