In xml doc, can I insert a reference to a method group? How?

Question

In C#, I can attach documentation for properties, methods, events, and so on, directly in the code using XML Documentation Comments.

I know how to insert a reference to a particular method:

<see cref="MethodName(TypeForArg1, TypeForArg2..)"/>

Is there a way to insert a reference to a method group? Where I've got multiple overloads of the same method name...

I tried

<see cref="M:MethodName"/>

..but that did not work.

score 3 · Accepted Answer · answered Oct 10 '09 at 17:43

3

Apparently there is no way to do this.

answered Oct 10 '09 at 17:43

Cheeso

189,189
101
473
713

Still true in 2023 using VS 2022. – Kit Jan 28 '23 at 12:51

score 2 · Answer 2 · edited Jan 28 '23 at 12:48

2

It appears that this behavior occurs in Visual Studio 2012-2022:

<see cref="MethodName"/>

Will generate a warning:

Ambiguous reference in cref attribute: 'MethodName'. Assuming '…', but could have also matched other overloads including '…'.

But adding an M: in front get's rid of the warning:

<see cref="M:MethodName"/>

edited Jan 28 '23 at 12:48

Kit

20,354
4
60
103

answered Aug 12 '13 at 17:35

p.s.w.g

146,324
30
291
331

This [documentation](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/processing-the-xml-file) indicates that the "M" prefix is valid in the generated XML, but I'm not sure that means this syntax is supported for method groups in particular. Do documentation tools like Sandcastle interpret these method-group references without error? – Jax Jul 06 '18 at 14:21
The in-VS experience (hovering over the symbol being documented) just shows the method name inline with no special markup (i.e. might as well replace the `see` with just the method group name itself. – Kit Jan 28 '23 at 12:50

score 0 · Answer 3 · answered Jul 06 '18 at 14:30

This is now supported in Sandcastle.

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

Note that this syntax does still have some limitations, as described this C# language feature request.

The syntax is not validated during build. Errors made while typing are not reported until if/when Sandcastle Help File Builder processes the comments.
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.

In xml doc, can I insert a reference to a method group? How?

3 Answers3