24

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?)

Hosam Aly
  • 41,555
  • 36
  • 141
  • 182

3 Answers3

15

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.

Marc Gravell
  • 1,026,079
  • 266
  • 2,566
  • 2,900
  • Thanks. Does the generator you use do this automatically? – Hosam Aly Jan 07 '09 at 09:32
  • I don't actually use a generator; the xml alone is fine for my usage (it is used by both intellisense and reflector). I don't usually need standalone documentation. – Marc Gravell Jan 07 '09 at 11:07
13

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.

Wilhelm
  • 1,868
  • 14
  • 21
  • 4
    Testing with SHFB 2014.5.31.0 indicates that the prefix must be `o:`, not `overloads:`. – tm1 Aug 26 '14 at 10:27
  • 1
    And C# compiler (tested for lang version 5.0) doesn’t issue a warning when using `o:`, so maybe that is the way to go. – binki Oct 02 '14 at 05:43
  • 1
    Tried with a see (rather than seealso) and had no luck at all. overloads: issues a compiler warning AND SHFB 14.5.31 ignores it. Also tried o: and M: and the compiler is okay but SHFB ignores them both. – Doug Clutter Jun 08 '15 at 18:38
  • I would like to say this should be the accepted answer, but then again OP didn't specify Sandcastle so, hmm... maybe not. Still very useful +1. – AnorZaken Jun 18 '17 at 15:46
  • 1
    Had problems referencing the overloads page, but finally i found the right syntax: What worked for me was using a big 'O', the full name of the method, and no parenthesis, like so: `Link name`. – Anders Apr 24 '21 at 20:09
5

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 ;)

AnthonyWJones
  • 187,081
  • 35
  • 232
  • 306