Question

I am curious as to why I get a compiler warning in the following situation.

/// <summary>This is class A
/// </summary>
public class A
{
    /// <summary>This is the documentation for Method A
    /// </summary>
    public void MethodA()
    {
        //Do something
    }
}

/// <summary>This is class B
/// </summary>
public class B : A
{
    /// <summary>This does something that I want to
    /// reference <see cref="MethodA"/>
    /// </summary>
    public void MethodB()
    {
        //Do something
    }

}

The warning states that “XML comment on ‘B.MethodB()’ has cref attribute ‘MethodA’ that could not be resolved.” If B inherits from A shouldn’t the compiler be able to see that method when generating the documentation without me specifying the parent class in the cref? If I change the cref to be cref="A.MethodA()" it works fine, but it seems like that’s unnecessary and is a pain to do, especially if I have to go up more than one level.

As a note to anyone testing this you have to be sure to “XML documentation file” checked in the Properties -> Build in order to see the warning.

Answer 1

If B inherits from A shouldn’t the compiler be able to see that method when generating the documentation without me specifying the parent class in the cref?

You would think so, but this is not the case. The XMLDoc parser needs the qualification to put the method into the correct scope of the class it belongs to. If the method is part of the same class (ie. not derived from a base class), you can do without the qualification, otherwise you need it.