Visual Studio 2015 / C# 6 / Roslyn can't compile XML comments in PCL project

Question

I just installed the fresh released Community Edition of Visual Studio 2015 (RTM) and I'm trying to get my open source project working under VS2015 and C# 6.0.

Some of my .cs are shared across projects. This way I'm able to build both a PCL version (with limited functionality) and a 'full' version of the core library.

For some reason however, some code files build properly in the full project, but fail when built in the PCL project (where everything compiles under C# 5 and Visual Studio 2013). The compiler seems to be unable to resolve a cref in an XML comment when building the PCL version. Here is a simplified code example that fails on my machine:

/// <summary></summary>
public class A
{
    // Compile error on next line:
    /// <summary><see cref="Y(Type)"/>.</summary>
    public void X() { }

    /// <summary></summary>
    /// <param name="x"></param>
    public void Y(Type x) { }

    /// <summary></summary>
    /// <param name="i"></param>
    public void Y(int i) { }
}

The compile error I'm getting is:

CS1580 Invalid type for parameter Type in XML comment cref attribute: 'Y(Type)' SimpleInjector.PCL

Weird thing is though that the IntelliSense support in the XML comments (Wow! we have IntelliSense in XML comments now!) actually works, and the method Y(Type) is selectable through the drop down list. But after selecting this, a compile error is generated (in PCL only).

My question of course is how to fix this? Is this a common problem? Could project's configuration have anything to do with this? Is this a known bug?

Answer 1

David Kean, a dev on the C#/VB languages team, responded quite quickly on Twitter and did some research on this. He reported back to me that this is in fact a bug and known limitation in Roslyn. After investigation, he reported the problem on Github here and here.

There are basically two problems here that together caused me to get stuck:

1. cref's to public members become ambiguous when an internal member is also in scope. In the case of Type, there seems to be an internal type named Type, but different than the public System.Type. Although this internal Type type, doesn't exist for my code, it does exist for Roslyn, and Roslyn gets confused.
2. The error message does not include fully qualified references in CS0419 to make it less confusing. Because the error message just states "Invalid type for parameter Type in XML comment cref attribute" it became hard for me to guess what the actual problem was.

The current work around for this problem is to fully qualify the types like this:

/// <summary><see cref="Y(System.Type)"/>.</summary>
public void X() { }

Note: The same holds for Assembly. You will have to fully qualify that type as System.Reflection.Assembly.