-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Closed
Description
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:
- ❗ 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.
- ❗ The syntax is extremely verbose.
- ❗ The syntax only works if there are more than one method with the same name.
- ❗ There is no syntax highlighting or editor support for this syntax.
I propose the following changes:
- 💡 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.)
- 💡 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.
Reactions are currently unavailable