This project is read-only.

Member visiblity in XML Doc

Topics: C# Language Design
Jun 5, 2014 at 8:30 AM
I've just started playing with VS14 and noticed that C# 6.0 is now adhering to member visibility in XML comments, i.e. I can't reference a protected (or private, internal) member in the xml doc of another class. Instead, I get a warning that "XML comment has cref attribute 'MyType.MyMember' that could not be resolved".

I'm curious as to the reasoning behind this change and if it is possible to revert this behavior. Simply deactivating the warning would possibly not do the trick, given that Roslyn apparently can't find the member and thus cannot create the correct reference within the documentation.

Best regards, Michael
Jun 5, 2014 at 1:26 PM
I'm curious, Why? If it can't be seen / accessible from that location, why would you need to Cref it?
If have a reason could you provide an example(s). So I can learn more.
Jun 5, 2014 at 9:28 PM
Well, I've got at least 50 references within my framework that are affected, but it could be more. Am not done getting project fixed yet, so it compiles again with Roslyn. So, that's immediate practical need :)

As for actual examples:
Well, there's the run-of-the-mill implementation note that's mostly there to educate people who are reading the source code. Using Cref, the references keep up to date even on renames. Then there's class families (e.g. sibling classes with different number of generic arguments) and I'm referencing a protected member only available in the sibling with more generic parameters to provide the users of my library with more context information on what to use how. I also have references from an interface to template methods provided by a default implementation, etc.

One could of course always argue that the documentation could be written a different way, but why not go the most direct path?

As for the actual why-not: the doc-compiler itself doesn't care about visibility when linking member references. All it cares about is getting the fully qualified name. This means that I can rewrite all the Crefs as fully qualified links, but that means sacrificing refactoring and compile time safety. Up until now (read, for the past decade), the C# compiler did that for me.

Best regards, Michael
Jul 18, 2014 at 10:06 AM
Okay, I just found that the issue is already in the issue tracker: https://roslyn.codeplex.com/workitem/69
Jan 27, 2015 at 8:35 PM
This issue has now been resolved according to https://github.com/dotnet/roslyn/issues/77#issuecomment-71510019
Marked as answer by MichaelKetting on 1/27/2015 at 12:35 PM