Defect: Can't document WinRT components



For each public type 'Foo' the compiler generates a corresponding internal type '<CLR>Foo'.

internal sealed class <CLR>YabaDabaDoo { ... }
public sealed class YabaDabaDoo { ... }

I believe the internal class comes first in the reflection pass and screws up the public class.

(Possible workaround: Temporarily change the target type of the WinRT component to class library. Use that DLL instead of the WINMD. Remember to set the target back to WinRT component.)
Closed Jan 10, 2014 at 1:59 AM by EWoodruff
The problem with WINMD assemblies is that the compiler takes the user's types and makes them all internal and prefixes their name with "". It then creates public types containing only the public members and tags them with the CompilerGenerated attribute. It's the last part that filters them out as typically you never want to see compiler generated stuff. As mentioned, the workaround is to check for a type of the same name prefixed with "" on types marked with the CompilerGenerated attribute and let them through if one is found. Note that if you enabled documentation of internals/privates you'll get all of the other "" prefixed types. I'm not going to try mapping or merging their internal/private members into the related public classes so that they appear as they do in the code as a single unified type. It's a low usage case that I'm not going to address.


EWoodruff wrote Jan 7, 2014 at 3:19 PM

SHFB doesn't compile the code so your workaround isn't feasible. The solution I plan on looking at is to ignore the CompilerGenerated attribute and pass the public class through if a class of the same name prefixed with "<CLR>" exists.

zlatko1 wrote Jan 8, 2014 at 4:07 AM

The workaround is not for you. It is for all the people who are suffering until you agree to fix the real problem. It is feasible - I did it multiple times. It is annoying, but it's better than nothing.

zlatko1 wrote Jan 9, 2014 at 4:49 AM

Please include this in the next release. A component's value prop is the API, and if the API can't be documented, the component can't be adopted. This work item is critical.

wrote Jan 10, 2014 at 1:59 AM

wrote Jan 10, 2014 at 2:00 AM

zlatko1 wrote Jan 10, 2014 at 5:02 AM

I can't judge how common this use case is. I'll take that with Windows.

As far as your repro goes, it doesn't really work. While members do get emitted under the internal "<CLR>" prefixed types, the /// comments are associated with the public classes (that don't get emitted). Thus the documentation is a bare skeleton with no text in it.

EWoodruff wrote Jan 10, 2014 at 7:42 PM

The public compiler generated class is passed through now so the comments do match up. The internal class obviously won't which is why I said I'm not going to try and map/merge the internal members into the public class.

Pointing wrote Mar 3, 2016 at 6:19 PM

Is this really fixed? In what version?

I have the version 2015.7.25.0 and Windows Runtime dlls aren't processed