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

【问题标题】：c# xml comment, cref can't reference method defined in base classc# xml注释，cref不能引用基类中定义的方法
【发布时间】：2018-06-20 19:26:34
【问题描述】：

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

我的设置有点像这样：

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 文档。

【问题讨论】：

您使用的是什么 .Net 版本/编译器/Visual Studio？我在这里对其进行了测试，但没有收到此警告。工具提示出现：“Uses RealFoo.Bar to do some magic”
@Tony 你在项目设置 -> 构建 -> XML 文档文件中打开了 XML 编译吗？
不，让我试试。在 .Net Core 2.1 上，Visual Studio 2017 15.8.0 预览版 2.0
警告 CS1591：缺少公开可见类型或成员的 XML 注释...'BaseFoo'、'BaseFoo.Bar()'、'RealFoo'、'DependentClass'
XML 生成成功。

标签： c# xml-comments

【解决方案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(); 直到你想要一个新的实现。

【讨论】：

我可能只是实现它或将 cref 引用更改为没有 cref 的纯文本，但是我想知道为什么会出现此警告。这是一个错误还是只是一个限制？
@Rob 我的钱是有限的，我明白为什么你不想爬取继承层次结构来查找虚拟方法，如果链接引用了一个，文档中会有点不清楚类型，但真的去了层次结构中的另一种类型。
接受了这个答案，因为这是我得到的最接近的答案，我想这是设计使然。我通过使用“使用 RealFoo.Bar（由实现）来做一些魔术”来解决它

【解决方案2】：

在这种情况下，我只是静态地编写 ClassName.Member，这样就可以了。

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

}

.NET Xml-Doc 似乎不知道继承。

【讨论】：