C# XML注释，cref无法引用基类中定义的方法。

Question

在我的代码库中，我有一个在基类中定义的方法，该基类被继承，但该方法尚未被覆盖。很可能将来会覆盖此方法以添加到基本实现中。

我的设置看起来像这样：

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()
    {

    }
}

由于Bar很有可能会在未来被覆盖，我希望将我的xmldoc未来证明并引用RealFoo.Bar而不是BaseFoo.Bar。

当我在代码中调用RealFoo.Bar()时，不会出现任何错误。但是当我在cref属性中这样做时，会收到以下警告：

警告 CS1574 XML注释具有无法解析的cref属性'Bar'。

这里我做错了什么，还是cref的限制？

我正在使用Visual Studio 2017，目标为netstandard2.0和net452，并在我的csproj中启用了XML文档。

- Rob

---

你正在使用哪个.Net版本 /编译器/Visual Studio？我在这里测试过，没有收到此警告。 工具提示显示：“使用RealFoo.Bar进行某些魔法”。 - Tony

@Tony 你在项目设置中打开了XML编译吗？路径是：构建 -> XML文档文件。 - Jonathon Chase

不，让我试试。在 .Net Core 2.1 和 Visual Studio 2017 15.8.0 预览版 2.0 上。 - Tony

警告 CS1591：公开可见的类型或成员缺少 XML 注释... 'BaseFoo'，'BaseFoo.Bar()'，'RealFoo'，'DependentClass' - Tony

XML已成功生成。 - Tony

Answer 1

你可以抑制此警告，但XmlDoc输出将用错误标记它。

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

或者，如果您相当确定将来会覆盖该方法，并且您打算使用XML输出生成文档，我建议您只需在RealFoo中实现它，如下：public override void Bar() => base.Bar(); 直到您想要一个新的实现为止。

- Jonathon Chase

---

我可能会实现它，或者将 cref 引用更改为不带 cref 的纯文本。但是我想知道为什么会出现这个警告。这是一个错误还是只是一个限制？ - Rob

@Rob 我认为限制是最好的选择，我能理解你不想爬取继承层次结构以查找虚拟方法的原因，而且如果链接引用了一个类型但实际上跳转到了继承层次结构中的另一个类型，文档会有点不清晰。 - Jonathon Chase

接受了这个答案，因为它是我得到的最接近的答案，我想这是设计上的。我通过使用“Uses RealFoo.Bar（由<see cref="BaseFoo.Bar"/>实现）来进行一些魔法”来解决它。 - Rob

Answer 2

在这种情况下，我只是静态地编写 ClassName.Member，就可以达到效果。

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

}

看起来 .NET 的 Xml-Doc 不知道继承。

- Nathan Smiechowski