С# комментарий xml, cref не может ссылаться на метод, определенный в базовом классе

В моей кодовой базе есть метод, определенный в базовом классе, базовый класс наследуется, но метод еще не переопределен. Этот метод, скорее всего, будет переопределен в будущем, чтобы добавить его в базовую реализацию.

Моя установка выглядит примерно так:

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, и у меня включена XML-документация в моем csproj.


c# xml-comments
person Rob    schedule 20.06.2018    source источник
comment
Какую версию .Net/компилятор/Visual Studio вы используете? Я проверил это здесь и не получил этого предупреждения. Появляется всплывающая подсказка: использует RealFoo.Bar для волшебства   -  person Tony    schedule 20.06.2018
comment
@ Тони, ты включил компиляцию XML в настройках проекта -> Сборка -> Файл документации XML?   -  person Jonathon Chase    schedule 20.06.2018
comment
Нет, позвольте мне попробовать это. на .Net Core 2.1, Visual Studio 2017 15.8.0 Preview 2.0   -  person Tony    schedule 20.06.2018
comment
предупреждение CS1591: отсутствует комментарий XML для общедоступного типа или члена... «BaseFoo», «BaseFoo.Bar()», «RealFoo», «DependentClass»   -  person Tony    schedule 20.06.2018
comment
XML был успешно сгенерирован.   -  person Tony    schedule 20.06.2018

Ответы (2)


arrow_upward
4
arrow_downward

Вы можете подавить это предупреждение, но вывод 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();, пока вам не понадобится новая реализация.

person Jonathon Chase    schedule 20.06.2018
comment
Я мог бы просто реализовать это или изменить ссылку cref на простой текст без cref, однако мне было интересно, почему появляется это предупреждение. Это баг или просто ограничение? - person Rob; 21.06.2018
comment
@Rob Мои деньги ограничены, я понимаю, почему вы не хотите сканировать иерархию наследования, чтобы найти виртуальный метод, и в документации было бы немного неясно, если бы ссылка ссылалась на один тип, но на самом деле уходила на другой тип в иерархия. - person Jonathon Chase; 21.06.2018
comment
Принял этот ответ, так как это самый близкий ответ, который я получил, я думаю, это сделано по замыслу. Я работал над этим, используя «Использует RealFoo.Bar (реализовано ‹see cref=BaseFoo.Bar/›) для волшебства» - person Rob; 25.06.2018

arrow_upward
1
arrow_downward

В этом случае я просто статически пишу ClassName.Member, что делает свое дело.

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

}

Похоже, .NET Xml-Doc не знает о наследовании

person Nathan Smiechowski    schedule 18.08.2020