XML Documents for Positional Records don't show example property

VS 17.2.5

This is sort of a follow-up to https://github.com/dotnet/roslyn/issues/52663, where the xml doc for records added the param element to the synthesized property, which is working great. However, to add an example, you still have to redefine the properties so that the output xml has the example in each of the property member elements.

For example, here is a simple record with a single property:

/// <summary>Simple Model</summary>
/// <param name="MyProperty" example="Example string">A basic parameter for a record</param>
public record MyModel(string MyProperty);

The (simplified) xml doc that is created as a result looks like this:

<doc>
    <members>
        <member name="T:MyModel">
            <summary>Simple Model</summary>
            <param name="MyProperty" example="Example string">A basic parameter for a record</param>
        </member>
        <member name="M:MyModel.#ctor(System.String)">
            <summary>Simple Model</summary>
            <param name="MyProperty" example="Example string">A basic parameter for a record</param>
        </member>
        <member name="P:MyModel.MyProperty">
            <summary>A basic parameter for a record</summary>  // Missing the  <example> element
        </member>
    </members>
</doc>

For the <member name="P:MyModel.MyProperty"> element, it doesn’t contain an <example> element, so the documentation (in Swagger for my use case) doesn’t show the proper example.

I can get around this by redefining the property, so the class ends up looking like this:

/// <summary>Simple Model</summary>
public record MyModel(string MyProperty)
{
    /// <summary>A basic parameter for a record</summary>
    /// <example>Example string</example>
    public string MyProperty { get; init; } = MyProperty;  // this is gross
};

This ends up creating the desired XML Doc below:

<doc>
    <members>
        <member name="T:MyModel">
            <summary>Simple Model</summary>
            <param name="MyProperty" example="Example string">A basic parameter for a record</param>
        </member>
        <member name="M:MyModel.#ctor(System.String)">
            <summary>Simple Model</summary>
            <param name="MyProperty" example="Example string">A basic parameter for a record</param>
        </member>
        <member name="P:MyModel.MyProperty">
            <summary>A basic parameter for a record</summary>
            <example>Example string</example>
        </member>
    </members>
</doc>

Expected Behavior: The ideal behavior here would be similar to the previous issue: Copy the example attribute from the model record into the Property member in the XML docs.

Actual Behavior: <param> comments on the record don’t copy the example attribute into the Property element, requiring us to redefine the property in the record.

[RikkiGibson]

Before beginning implementation work here let’s verify whether we consider this a bug-fix level change, or a language-level change, etc., get a specific design in place and get buy-in on that design. Tagging @jcouv for visibility.

I’m about to go out of office for a few weeks so won’t be able to assist with this for a while.

[Markemp]

example= in the param tag would be for simple primitives for that parameter, specifically to allow the xml documentation to display an example value instead of the type (string, float, etc). For the simple records shown in the original post, you cut the vertical space from 7 lines to just 3 if you have the ability to define the parameter example on the record.

If your parameter is a more complicated type (a class) or needs more explanation (requiring a <code> block for example), you still have the traditional method of defining a property with the { get; init; } style.

We use records a lot for API requests/responses, and we’d like to keep the records as terse as possible, and for the swagger docs to provide meaningful examples for the API consumers (Widget Name instead of string). However, with the current implementation we have to redefine the parameter into the property. I’m not sure if this changes anything at the compiled code level. It would be interesting to compare the difference between the 2 examples above, but that’s a bit beyond my ability.

Also, there is an edge case where if the properties are explicitly created, and then docs are added on both the record (as param) and the property (as summary), the property doesn’t get added from either source. I’ve added a couple of unit tests (attached as AdditionalTests.cs.txt based off of the PositionalRecord_06 test to demonstrate this. The tests are passing, but probably shouldn’t. (Or just as likely I overlooked something in the test itself… 😳)

            var source = @"
/// <summary>The record.</summary>
/// <param name=""Item"">Item within the record.</param>
record Rec(string Item)
{
    <summary>Item within the record</summary>
    <example>An example</example>
    public string Item { get; init; } = Item;
}
";

I’ve also attached some additional unit tests on how I imagine the example attribute working, in the event this helps with the design.

AdditionalTests.cs.txt AdditionalTestsWithExampleParam.cs.txt