Distinguish between overloaded methods in XML-Comments

XML-Comments are quite handy when documenting public methods / classes. But what about method overloads in “see”-Tags?

Today when documenting some methods of a class using XML-Comments, I got a ReSharper message saying

Ambiguous reference Bar

However, ReSharper did not provide any automatic solution. So I had to find one myself

The class itself look like the following one:

public sealed class Foo
{
    /// <summary>
    /// Bars this instance. <!-- I simply love GhostDoc   -->
    /// </summary>
    /// <remarks>Calling this method is equivalent to calling <see cref="Bar"/> and passing <c>0</c> as parameter.</remarks>
    public void Bar()
    {
        this.Bar(0);
    }
    /// <summary>
    /// Bars this instance.
    /// </summary>
    /// <param name="argument">The argument.</param>
    public void Bar(int argument)
    {
        //TODO Bar this instance
    }
}

Notice the <see cref=”Bar” />.

After doing some research, I found a link to Processing the XML File in cref Attribute.

With its help I was able to write the following solution:

/// <remarks>Calling this method is equivalent to calling <see cref="Bar(System.Int32)"/> and passing <c>0</c> as parameter.</remarks>

Now this syntax seems quite logical to me.

Note: Only specifying “int” between the braces seems to be possible, too. However, ReSharper still shows its warning in combination with certain types (I was using a System.Threading.Dispatcher).

About these ads