Proposal: XML doc comments for multiple results by tuple

[ufcpp]

The most common use case of tuples is multiple results. Tuples are counterpart of method parameters and param tags in XML doc comments has a name attribute for each parameter. Thus, returns tags should have a name attribute too.

So far, I have to write doc comments as the following code. The method F has two results s and t, but the doc comment cannot have their names.

/// <summary>
/// </summary>
/// <param name="x"></param>
/// <param name="y"></param>
/// <returns>s is [description for s], t is [description for t]</returns>
static (int s, int t) F(int x, int y)
{
    return (x + y, x - y);
}

I'd like to write as the following. Let the returns tags have a name attribute for tuple element name.

/// <summary>
/// </summary>
/// <param name="x"></param>
/// <param name="y"></param>
/// <returns name="s">[description for s]</returns>
/// <returns name="t">[description for t]</returns>
static (int s, int t) F(int x, int y)
{
    return (x + y, x - y);
}

[dsaf]

I thought tuples are not recommended for public "user-facing" code?

[DavidArno]

@dsaf,

I thought tuples are not recommended for public "user-facing" code?

The very first example on the Quickstart guide for tuples (C# 7.0) page shows a public class with a public method that returns a tuple. So I'm not sure everyone is agreeing with that idea.

Do you have a reference though for that recommendation as I can't think of reason to adopt that approach, but no doubt I'm missing something.

[dsaf]

@DavidArno That sample is not an argument. However, given that naming metadata is emitted for compiled code, I guess there is no reason not to use them now. They will actually be more usable than common lambdas #12716!

[MartinJohns]

I thought tuples are not recommended for public "user-facing" code?

This would be a guideline, but it's not enforced by the compiler. We need a way to properly document return types.

[ufcpp]

Ported to dotnet/csharplang#145