Roslyn: Figure out XML docs for positional records

[jcouv]

How do we specify xml docs for positional members (which define both parameters and properties)?

record Person(string First, string Last);

[jcouv]

From discussion on 7/15/2020, we're going to go with a minimalist approach to start:

1. compiler will carry over <param> tags from record types to constructor parameters
2. IDE may choose to adjust inheritance logic so that properties show some information from associated parameter
3. synthesized methods (Equals and such) won't include any boilerplate documentation

[333fred]

Make sure that CS1591 (missing XML comments) is not reported for these carry-overs.

[RikkiGibson]

Is further action needed by the compiler team for 16.8?

[jcouv]

@RikkiGibson Yes, we'd like to do (1) from plan above: "compiler will carry over tags from record types to constructor parameters".
This can be pushed out to 16.9 if necessary.

[buvinghausen]

@jcouv is there currently any way to get the compiler not to throw the CS1591 warning other than doing a pragma warning disable?

I've tried lots of options and usually they add even more warnings than just the CS1591.

[jcouv]

@buvinghausen The CS1591 is complaining that the properties don't have documentation. One solution at the moment is to use explicit properties (public C Name { get; init; } = Name;) and place documentation on it.

[buvinghausen]

@jcouv I understand the context of CS1591. I was hoping there was a workaround other than using explicit properties or not having any documentation (via pragma disable) at all. Bummer. Hopefully this gets sorted soon. Thank you for the clarification.

[RikkiGibson]

Let's make sure that completion works properly on nominal records as well, particularly in the following scenarios analogous to method parameters:

That is, typing a /// on the line before a record declaration should include <param> tags for all the record primary constructor parameters, and within a /// block the <param> elements should be suggested with appropriate parameter names, based on which parameters haven't been documented yet.