c#xml注释，cref不能引用基类中定义的方法

Question

In my codebase I have a method defined in a base class, the base class is inherited, but the method is not yet overridden. This method will very likely be overridden in the future to add to the base implementation.

My setup looks a bit like this:

public abstract class BaseFoo
{
    public virtual void Bar()
    {
        //default implementation
    }
}

public class RealFoo : BaseFoo
{
    //extra code, does *NOT YET* override Bar but might in the future
}

public class DependentClass
{
    /// <summary>
    /// Uses <see cref="RealFoo.Bar"/> to do some magic
    /// </summary>
    public void SomeMethod()
    {

    }
}

Since it's very likely that Bar will be overridden in the future, I would like to future proof my xmldoc and reference RealFoo.Bar instead of BaseFoo.Bar .

When I call RealFoo.Bar() in my code, no errors occur. When I do so in a cref attribute I get the following warning:

Warning CS1574 XML comment has cref attribute 'Bar' that could not be resolved.

Am I doing something wrong here or is this just a limitation of cref?

I'm using visual studio 2017, targeting netstandard2.0 and net452, and I have XML documentation enabled in my csproj.

Answer 1

You can suppress this warning, but the XmlDoc output will mark it with an error.

<member name="M:MyApplication.DependentClass.SomeMethod">
    <summary>
        Uses <see cref="!:RealFoo.Bar"/> to do some magic
        <!--            ^- indicates an error -->
    </summary>
</member>

Alternatively, if you're pretty sure that you're going to override the method in the future, and you are intending to generate documentation with the XML output, I would just implement it in RealFoo as public override void Bar() => base.Bar(); until you want a new implementation.

Answer 2

In this case I just statically write ClassName.Member which does the trick.

/// <summary>
/// Uses <see cref="BaseFoo.Bar"/> to do some magic
/// </summary>
public void SomeMethod()
{

}

It looks like .NET Xml-Doc does not know about inheritance