Skip to content

Ability to reference a method group in XML comment #45

@sharwell

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions