Why can't I reference the accessible members in a base class from within XML documentation comment tags in a derived class?

Question

Say I have this:

internal abstract class Animal
{
    internal bool IsExtinct { get; set; }
}

internal sealed class WoollyMammoth : Animal
{
    internal int WeightLbs { get; set; }

    /// <summary>
    /// Construct a new instance with <see cref="IsExtinct"/> // this throws an error "XML comment has cref attribute 'IsExtinct' that could not be resolved".
    /// set to "true" and <see cref="WeightLbs"/> // this works just fine.
    /// initialized to 0.
    /// </summary>
    WoollyMammoth()
    {
        // no problem with either of these, of course.
        IsExtinct = true; 
        WeightLbs = 0;
    }
}

Why am I getting an error when trying to reference the IsExtinct property, defined in the base class, from the <see/> XML comment tag? I can access properties that are defined in the derived class, like WeightLbs.

Is the property maybe private? – Saša Ćetković Jun 15 '17 at 20:42 — Saša Ćetković, Jun 15 '17 at 20:42

score 8 · Accepted Answer · answered Jun 15 '17 at 21:42

To reference a base class symbol, use a qualified name: <see cref="Animal.IsExtinct"/>.

There is no particular reason why this should be required. The Roslyn code base contains a test which specifically tests that base class symbols are not found (CrefTests.TypeScope4) which mentions that the reason is simply is because that is what the previous compiler did:

// As in dev11, we ignore the inherited method symbol.

It looks like a historic accident, and since the workaround is trivial it's unlikely to be changed.

Why can't I reference the accessible members in a base class from within XML documentation comment tags in a derived class?

1 Answers1