How to make a cref to method overloads in a <seealso> tag in C#?

Question

I see in MSDN links such as "CompareOrdinal Overloads". How can I write such a link in C#?

I tried:

<seealso cref="MyMethod">MyMethod Overloads</seealso>

But the compiler gives me a warning about being an ambiguous reference for the method which has other overloads.

(Beginner question: do I actually need to write this tag to link to the overloads, or is it automatically generated by documentation processors?)

Answer 1

To target specific members, I believe you just match the signature:

/// <seealso cref="Foo(int)"/>
static void Foo() { }
/// <seealso cref="Foo()"/>
/// <seealso cref="Foo(float)"/> <------ complains
static void Foo(int a) { }

To be honest, I'm not sure how to generate an "all overloads" link; I'd assume that any sensible generator did this automatically.

Answer 2

Using Sandcastle it is simple:

<seealso cref="overloads:FullyQualifiedMyMethod">MyMethod Overloads</seealso>

FullyQualifiedMyMethod is the complete route you need to reach the overload, including namespaces and classes, i.e.: System.Linq.Enumerable.Sum

However VB compiler issues a warning saying the attribute can not be resolved, which can be ignored.

Answer 3

Xml documentation doesn't have a means to reference all overloads of a method.

The most popular documentation generator for C# projects is Sandcastle. It will automatically create a link to an overloads list page if necessary. Hence in a members list page the name of an overloaded method will appear only once, clicking it will navigate you to the list of overloads page for that method and from there to a specific overload.

Placing a link to the overloads list page in Xml documentation would require intimate knowledge of the external tool being used and probably not a good idea.

If you really must have this then perhaps one way is to use an anchor with a specificaly formed ID. Most document generators provide some arcane means of pre or post processing generated files and should give you the opportunity to pick these anchors out and provide an appropriate href for them.

OTH, it may be more trouble than its worth ;)