c# xml comment, cref can't reference method defined in base class

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.

What .Net version / compiler / Visual Studio are you using? I tested it here and did not get this warning. The tooltip appears: "Uses RealFoo.Bar to do some magic" — Tony, Jun 20 '18 at 19:32
@Tony did you turn on XML compilation in the project settings -> Build -> XML documentation file? — Jonathon Chase, Jun 20 '18 at 19:53
No, let me try that. on .Net Core 2.1 , Visual Studio 2017 15.8.0 Preview 2.0 — Tony, Jun 20 '18 at 19:56
warning CS1591: Missing XML comment for publicly visible type or member ... 'BaseFoo', 'BaseFoo.Bar()', 'RealFoo', 'DependentClass' — Tony, Jun 20 '18 at 19:59

score 11 · Accepted Answer · edited Oct 28 '21 at 15:46

11

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.

edited Oct 28 '21 at 15:46

funie200

3,688
5
21
34

answered Jun 20 '18 at 20:01

Jonathon Chase

9,396
21
39

I might just implement it or change the cref reference to a plain text without cref, I was however wondering why this warning occurs. Is it a bug or just a limitation? – Rob Jun 21 '18 at 07:05
@Rob My money is on limitation, I can see why you wouldn't want to crawl an inheritance hierarchy to find a virtual method, and it would be a bit unclear in documentation if the link referenced one type but really went to another type in the hierarchy. – Jonathon Chase Jun 21 '18 at 15:10
Accepted this answer since it's the closest answer I got, I guess it's by design. I worked around it by using 'Uses RealFoo.Bar (implemented by ) to do some magic' – Rob Jun 25 '18 at 12:12

score 6 · Answer 2 · edited Dec 21 '21 at 17:26

6

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.

edited Dec 21 '21 at 17:26

d219

2,707
5
31
36

answered Aug 18 '20 at 13:38

Nathan Smiechowski

356
4
11

c# xml comment, cref can't reference method defined in base class

2 Answers2