Documentation comments for properties of positional records in C#

Question

If I have a positional record like this:

public record Version(int Major, int Minor);

it seems that I can only provide a <summary> documentation, like this:

/// <summary>
/// Version record
/// </summary>
public record Version(int Major, int Minor);

Is it possible to document the Major and Minor properties (possibly constructor arguments as well) while keeping the short record syntax?

This is [still under development](https://github.com/dotnet/roslyn/issues/44571) — canton7, Dec 17 '20 at 13:48
Not sure but try this /// The major. /// The minor. Or install GhostDoc, a great plugin who auto-comment your code — anthony chaussin, Dec 17 '20 at 13:48
Does typing ```///``` and hitting space generate the XML comment with the parameter? Which visual studio version are you using? That works for me (vs 19, version 16.7.1) and I don't have ghostDoc installed. — devsmn, Dec 17 '20 at 13:52

Yair Halberstadt · Accepted Answer · 2023-03-19T09:16:15.187

From .NET 6.0.300 and up, 'param' docs on the primary constructor now automatically propagate to the 'summary' doc on the property.

Original answer below.

As canton7 points out this is still under development.

The best workaround right now to document the property and the parameters is to define the property explicitly, whilst keeping the record positional:

/// <summary>
/// Version record
/// </summary>
/// <param name="Major">Major constructor parameter</param>
/// <param name="Minor">Minor constructor paramater</param>
public record Version(int Major, int Minor)
{
    /// <summary>
    /// Major Property
    /// </summary>
    public int Major { get; init; } = Major;

    /// <summary>
    /// Minor property
    /// </summary>
    public int Minor { get; init; } = Minor;
}

This is slightly shorter than defining the constructor yourself, but more usefully, once support is added you can move the documentation to the primary constructor whilst knowing that this won't change the generated code in any way. Also it is necessary to do it this way if you want to inherit from another positional record.

and the new issue to follow: https://github.com/dotnet/roslyn/issues/52663 — momvart, Nov 17 '21 at 08:33
It's no longer necessary to do this in .NET 6.0.300 and up. 'param' docs on the primary constructor now automatically propagate to the 'summary' doc on the property. https://stackoverflow.com/a/75579257/2855742 — Rikki Gibson, Mar 18 '23 at 00:00

score 2 · Answer 2 · answered Feb 27 '23 at 10:25

As of .NET SDK 6.0.300 and Visual Studio 2022 version 17.2, this is accomplished by using the <param name="property-name">parameter summary</param> tag. Thus the following would accomplish the desired result:

/// <summary>
/// Version record
/// </summary>
/// <param name="Major">Major version</param>
/// <param name="Minor">Minor version</param>
public record Version(int Major, int Minor);

score 1 · Answer 3 · answered Dec 17 '20 at 14:20

1

You can document it like this :

/// <summary>
/// Version record
/// </summary>
/// <param name="Major">Major version</param>
/// <param name="Minor">Minor version</param>
public record Version(int Major, int Minor);

And then you have the documentation while using it in-code :

answered Dec 17 '20 at 14:20

Gambi

464
4
12

2

This doesn't add documentation to the property, however. – canton7 Dec 17 '20 at 14:33
I'm wondering why someone would like to document and integer. If you need more documentation, you set a class property where the class is documented. – Gambi Dec 17 '20 at 14:47

Documentation comments for properties of positional records in C#

3 Answers3