order of explicit xml docs with `inheritdoc`

Currently, if you try to override XML docs from an inheritdoc they must appear above the inheritdoc.

Examples (that are currently failing)

/// <summary>hello world</summary>
/// <typeparam name="T">hello world</typeparam>
public class A<T> { }

/// <inheritdoc/>
/// <typeparam name="T">goodbye world</typeparam>
public class B<T> : A<T> { }

/// <inheritdoc cref="A{T}"/>
/// <typeparam name="T">goodbye world</typeparam>
public class C<T> { }

public class D
{
    /// <summary>hello world</summary>
    /// <typeparam name="T">hello world</typeparam>
    void Method1<T>() { }

    /// <inheritdoc cref="Method1{T}"/>
    /// <typeparam name="T">goodbye world</typeparam>
    void Method2<T>() { }
}

• B<T>
  • B<T> inheritdoc's from A<T> and attempts to override the XML docs for T but due to how the ordering of the XML docs are currently processed, it is not overriding. The XML docs for T on B<T> say hello world even though it has goodbye world directly on it.
• C<T>
  • Same as the B<T> example but a cref is used rather than class inheritance. The XML docs for T on C<T> say hello world even though it has goodbye world directly on it
• D.Method2<T>
  • Same as the other examples, but using methods rather than classes. The XML docs for T on D.Method2<T> say hello world even though it has goodbye world directly on it

This issue exists for all member types, not just methods and classes as shown in these examples.

Bug? Or just add a warning?

Personally, I am totally fine with how roslyn works, but I just want a warning to be in place if I accidentally add XML that is being hidden by an above inheritdoc.

However, @sharwell said this is a bug (explicit docs should always override inheritdoc regardless of order). https://gist.github.com/ZacharyPatten/cb37ae76a01b68d34efdfe7de7c041c4

Why am I okay with how roslyn currently works? Consider the scenario where you have multiple inheritdocs:

/// <summary>hello world</summary>
/// <typeparam name="T1">hello world</typeparam>
public class E<T1> { }

/// <summary>goodbye world</summary>
/// <typeparam name="T2">goodbye world</typeparam>
public class F<T2> { }

/// <inheritdoc cref="E{T1}"/>
/// <inheritdoc cref="F{T2}"/>
public class G<T1, T2> { }

• The summary on G<T1, T2> is hello world because the E<T1> inheritdoc comes before the F<T2> inheritdoc.

There is no getting around the concept that order matters when using multiple inheritdocs. Yes there can be an exclusion for explicit XML docs on members, but I kinda like the idea of enforcing the order of the docs.

Conclusion

If this is considered a bug, then a fix would be nice.

If this is not considered a bug, then a compiler warning would be nice.