Proposal: multiple returns tags and name attributes in doc comments for a tuple return value

[ufcpp]

Ported from dotnet/roslyn#13216

multiple returns tags and name attributes in doc comments for a tuple return value

Summary

The most common use case of tuples is to return multiple values from a method. Tuples are designed as counterpart to method parameters. And param tags in XML doc comments has a name attribute for each parameter. Thus, returns tags should have a name attribute for each tuple element too.

Motivation

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);
}

This is inconvenient because the following features can not work well.

• rename refactoring
• CS1573 warning

Proposal

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);
}

Drawbacks

This feature requires implementation in not only a C# compiler but also related tools such as Sandcastle.

[jnm2]

I think this is valuable for ideological reasons. Tuples should be like argument lists as much as possible.

[gafter]

/cc @MadsTorgersen @jcouv @VSadov

[jcouv]

I wonder if the proposal (multiple returns in xml doc) is the best way to address the general problem. Consider a method that returns List<(int s, int t)>. The problems you describe with rename refactoring would still exist.

My initial reaction would be to keep a single returns xml tag, but allow references to tuple names within that tag. But I can come up with more troublesome scenarios where this breaks down too. For instance, a method returning (int, (int, int second) second). Would an xml tag referring to second refer to the outer second or the inner second?

[alrz]

Tuples should be used as self-explanatory and short-lived combination of values. I think a better solution is to use a record instead, if we want to provide documentation. Same would be applied to generic delegates, you will probably define a special delegate type if you're going to document parameters etc.

[jnm2]

But I can come up with more troublesome scenarios where this breaks down too. For instance, a method returning (int, (int, int second) second). Would an xml tag referring to second refer to the outer second or the inner second?

I don't think this breaks down. If (int a, (int c, int d) b) was an argument list, you could only <paramref> a and b. Inner names cannot not be referenced and their names would not conflict. Makes sense that you could only reference top-level tuple names in <returns> as well.

[VSadov]

Yes, tuples can nest and nesting may allow for leaf tuples to have same names.
I am not sure "multiple returns" would handle nested tuple. I think @jcouv is right - there should be just one return, but if there is a way to refer to elements, then they can be individually documented.

[HaloFour]

I agree with @alrz, tuples really aren't well suited for public APIs or scenarios where you'd need or want to document them, at least beyond what the element name metadata already provides. If you have an accessible method that returns a complicated tuple (particularly nested) and you feel that you need to use XML documentation, you probably should be explicitly declaring a concrete class.

[jnm2]

The other thing about public APIs is, what happens when you want to add a field to the return type? That's only a non-breaking change if you own and mutate the type definition. I don't know if we should try too hard to support them except for the ideological parity with argument lists. And here maybe it's just not worth it?

[scottdorman]

I agree that something like this should be supported as it does provide parity with argument lists. As for the arguments that tuples shouldn't be used as a return type in a public API, I agree that the "original" tuples (all of the Tuple<T> classes) shouldn't be used as we have no control over the name of the properties/items/elements (whatever you want to call them) inside the tuple. However, tuples of the form (int s, int t) seem reasonable to use as a return type and that it's also reasonable to want to properly refer to them in the <returns> doc comment. It seems like this would also apply when we get record types.

Instead of multiple <returns> though, would it make more sense to introduce a parallel to <paramref>, perhaps called <returnref> or <tupleref>? In the original example, the function still only returns a single return type, it just so happens that the return type is a "complex" type of (int s, int t). It seems more reasonable (and probably more flexible) to write this as

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

[jnm2]

@scottdorman I would expect <returnref> to be used inside <summary> the same way <paramref> is currently, but here you're using <returnref> as the equivalent of <param>.

[scottdorman]

@jnm2 I can use <paramref> in other places, not just in the <summary>, including in <param>. I think that's valid, as I might want to write the doc comment like

/// <returns>When this method returns, <returnref name="s">is a positive non-zero value</returnref>
/// and <returnref name="t">is a negative value</returnref>.</returns>

[jnm2]

@scottdorman You're right, I didn't communicate that very well. Let me put it this way.

<paramref> contains no documentation (it's self-closing) and is used purely as a link to the <param> documentation.

But your <returnref> does contain documentation and is not used purely as a link to the <returns> documentation.

[HaloFour]

@scottdorman

What happens in the case of nested tuples?

static (int s, (int s, int t) t) F(int x, int y) { ... }

[jnm2]

@HaloFour #145 (comment)

[scottdorman]

@jnm2 Correct. So maybe <returnref> isn't the best name, but I think the idea still works. It would be closer to <see>.

@HaloFour I would think I'd be able to refer to it as <returnref name="s"> which refers to the outermost s and <returnref name="t.s"> which refers to the s element of the t element.

[ufcpp]

@scottdorman

I'd be able to refer to it as <returnref name="s"> which refers to the outermost s

How about the case of generic type arguments?

static Task<(int s, int t)> FAsync() { ... }

Can s and t be considered as outermost?

[scottdorman]

@ufcpp I think so. In that case, you're still returning a single Task<T>, where T is of type (int s, int t), so I think the naming rules of <returnref name="s"> would still make sense.

[HaloFour]

Dictionary<(int a, int b), (int a, int b)> ?

[scottdorman]

@HaloFour Nice one! :)

<returnref name="a`1">
<returnref name="a`2">

or

<returnref name="a#1">
<returnref name="a#2">

[jnm2]

Given all these examples, I'm starting to dislike the whole idea. From a pragmatic standpoint, what do you expect to see in the IDE? You only see <param> contents when typing arguments. So if you have:

(c, d) = Foo(a, b);

There's no point in <returns> docs for c and d specifically because IntelliSense will never show them because when you're typing them, you haven't typed Foo yet.

[scottdorman]

@jnm2 XML doc comments are for more than just IntelliSense, though. Yes, I don't think these would show up in IntelliSense.

[mattiasw2]

Anything done on this? What should the syntax be? As people go for more functional style programming, in order to get concurrency correct, more and more tuples will be returned by functions, and named tuples really makes this simple. We need to be able to document it in a standard way.

[egvijayanand]

This is a much-needed feature, especially when working with the return type and referring it by Item1, Item2, and so on.

Need to know exactly what its function is or at least a hint about what exactly it is.

Having to scroll and look into the method signature every single time, painful.

Regards,
Vijay Anand E G

[crozone]

If we just had the ability to reference tuple names in <see cref="ValueTuple{T1, T2}"/> tags, this would still be a big help. Then we could at least write <returns> docs using this, as well as reference tuple names in the <summary> or anywhere else it's relevant.

For example:

/// <returns>
/// A <see cref="ValueTuple{Color Color, Boolean IsDark}"/>,
/// where the <see cref="ValueTuple{Color Color, Boolean IsDark}.Color"/> is the background color,
/// and the <see cref="ValueTuple{Color Color, Boolean IsDark}.IsDark"/> describes whether the background color is considered dark. 
/// <see cref="ValueTuple{Color Color, Boolean IsDark}.IsDark"/> is indented to facilitate choosing a suitable foreground text color that
/// maximizes readability and contrast on the background color. 
/// </returns>

or, potentially more ideally, remove the need to use ValueTuple in the cref and simply allow tuple syntax:

/// <returns>
/// A <see cref="(Color Color, Boolean IsDark)"/>,
/// where the <see cref="(Color Color, Boolean IsDark).Color"/> is the background color,
/// and the <see cref="(Color Color, Boolean IsDark).IsDark"/> describes whether the background color is considered dark. 
/// <see cref="(Color Color, Boolean IsDark).IsDark"/> is indented to facilitate choosing a suitable foreground text color that
/// maximizes readability and contrast on the background color. 
/// </returns>