Ability to reference a method group in XML comment

[sharwell]

Currently the following works:

/// <summary>
/// Reference to a method group with one item: <see cref="Foo"/>
/// </summary>
void Foo() { }

However, the following does not work:

/// <summary>
/// Reference to a method group with two items: <see cref="Foo"/>
/// </summary>
void Foo() { }
void Foo(int x) { }

The specific warning produced is:

warning CS0419: Ambiguous reference in cref attribute: 'Foo'. Assuming 'TypeName.Foo()', but could have also matched other overloads including 'TypeName.Foo(int)'.

To reference a method group, the following syntax is required:

/// <summary>
/// Reference to a method group with two items:
/// <see cref="O:Full.Declaring.Namespace.TypeName.Foo"/>
/// </summary>
void Foo() { }
void Foo(int x) { }

This is problematic for the following reasons:

1. ❗ The syntax is not validated during the build. Errors made while typing are not reported until if/when Sandcastle Help File Builder processes the comments.
2. ❗ The syntax is extremely verbose.
3. ❗ The syntax only works if there are more than one method with the same name.
4. ❗ There is no syntax highlighting or editor support for this syntax.

I propose the following changes:

1. 💡 If no argument list is provided and the method group contains exactly one method, compile the comment as a direct reference to that method. (This is how the compiler already behaves for this case.)
2. 💡 If no parameter list is provided and the method group contains more than one method, compile the comment as a reference to the overloads of the method, with the O: form listed above.

[SunsetQuest]

+1 for me. I was just searching online for a solution and found this. This would be a nice change. Very often it seems like there are multiple signatures for a function and I can either ....

• pick a signature and add it - this only shows a single item however
• use the "O:" trick as it is now but it has drawbacks (not checked, more of a hack)
• list them all - having to list them all and maintain them as they change is not that convenient.

Another idea (maybe) would be to use a wildcard at the end

This might be a little cleaner . It might also be cool to do a Full.Declaring.Namespace.TypeName.ConvertFrom_to_(*) but that might be getting carried away and might not be used often.

[dougclutter]

+1 for me.

[miloush]

+1 and me. I actually believe this worked before Roslyn, i.e. the method group would have been referenced by "Foo" only.

On a related note, I would prefer if the Intellisense did not add the method parameters into the XML documentation unless I wanted to specifically refer the particular overload - especially I don't want the parameters if there is only one overload. But I guess that would be solved with this issue, if method groups were offered in the list.

[mozzis]

I can add that even the fully qualified overload does not work when documenting C++/CLR functions. The result in HTML docs is just <span class="nolink">OverloadMethod</span> where "OverloadMethod" is the name of the overloaded method you are trying to cross-reference.

[gafter]

We are now taking language feature discussion on https://github.com/dotnet/csharplang for C# specific issues, https://github.com/dotnet/vblang for VB-specific features, and https://github.com/dotnet/csharplang for features that affect both languages.

[miloush]

Is this language feature discussion as it worked before and potentially regressed?

[gafter]

@miloush I don't have evidence one way or the other, but if the behavior regressed it could make sense to open it as a bug report (regression) against the compiler.

[gafter]

This issue has been moved to dotnet/csharplang#320