Fix XML documentation with colliding Win32 ABI types

[Sergio Pedri (Sergio0694)]

Summary

Fix friendly-overload XML documentation errors when another referenced assembly embeds an internal Win32 ABI type with the same full name as a public type supplied by the product ABI assembly. The compiler messages are (the CreateWindowEx signature is abbreviated here; the full messages appear below):

Diagnostic	Compiler error message
CS1580	Invalid type for parameter winmdroot.Foundation.PCWSTR in XML comment cref attribute: 'CreateWindowEx(...)'
CS1574	XML comment has cref attribute 'CreateWindowEx(...)' that could not be resolved

CS1580 is reported for each of the two PCWSTR parameters; CS1574 is reported for the unresolved reference as a whole.

• Preserve the native method's documentation by copying it to the friendly overload only in ambiguous-type cases, omitting <param> docs for parameters the overload removes. Keep normal <inheritdoc cref> generation unchanged otherwise.
• Use canonical documentation IDs for the related PWSTR member links and add two-assembly regression coverage for CreateWindowEx, optional parameters, and the extension-receiver path.

Reproduction

The supplied repro uses CsWin32 0.3.333 and Win32Metadata 71.0.26-preview:

1. Interop.Abi generates public FindWindow interop, including Windows.Win32.Foundation.PCWSTR.
2. Interop.Consumer references that project and Shmuelie.WinRTServer 2.2.1, which embeds an internal type with the same full name. The consumer requests CreateWindowEx with XML documentation enabled.
3. Building the consumer with TreatWarningsAsErrors=true reports two CS1580 diagnostics and one CS1574. Removing Shmuelie.WinRTServer makes the build pass.

The C# method signature correctly binds to the public ABI type. XML cref binding also considers the inaccessible duplicate, so it cannot resolve the friendly overload's reference to the native overload. Fully qualifying the type names does not remove the conflict.

Offending generated code and diagnostics

Here is the generated native declaration from the regression before the documentation fix (surrounding attributes and documentation omitted):

using winmdroot = global::Windows.Win32;

internal static extern unsafe winmdroot.Foundation.HWND CreateWindowEx(winmdroot.UI.WindowsAndMessaging.WINDOW_EX_STYLE dwExStyle, [Optional] winmdroot.Foundation.PCWSTR lpClassName, [Optional] winmdroot.Foundation.PCWSTR lpWindowName, winmdroot.UI.WindowsAndMessaging.WINDOW_STYLE dwStyle, int X, int Y, int nWidth, int nHeight, [Optional] winmdroot.Foundation.HWND hWndParent, [Optional] winmdroot.UI.WindowsAndMessaging.HMENU hMenu, [Optional] winmdroot.Foundation.HINSTANCE hInstance, [Optional] void* lpParam);

The friendly overload accepting string parameters has this generated documentation, which fails to bind despite the valid native declaration:

/// <inheritdoc cref="CreateWindowEx(winmdroot.UI.WindowsAndMessaging.WINDOW_EX_STYLE, winmdroot.Foundation.PCWSTR, winmdroot.Foundation.PCWSTR, winmdroot.UI.WindowsAndMessaging.WINDOW_STYLE, int, int, int, int, winmdroot.Foundation.HWND, winmdroot.UI.WindowsAndMessaging.HMENU, winmdroot.Foundation.HINSTANCE, void*)"/>

The compiler reports CS1580 for each of the two PCWSTR parameters (invalid parameter type in an XML reference) and CS1574 for the entire reference (XML reference could not be resolved). Representative messages from the failing regression:

CS1580: Invalid type for parameter winmdroot.Foundation.PCWSTR in XML comment cref attribute: 'CreateWindowEx(winmdroot.UI.WindowsAndMessaging.WINDOW_EX_STYLE, winmdroot.Foundation.PCWSTR, winmdroot.Foundation.PCWSTR, winmdroot.UI.WindowsAndMessaging.WINDOW_STYLE, int, int, int, int, winmdroot.Foundation.HWND, winmdroot.UI.WindowsAndMessaging.HMENU, winmdroot.Foundation.HINSTANCE, void*)'
CS1574: XML comment has cref attribute 'CreateWindowEx(winmdroot.UI.WindowsAndMessaging.WINDOW_EX_STYLE, winmdroot.Foundation.PCWSTR, winmdroot.Foundation.PCWSTR, winmdroot.UI.WindowsAndMessaging.WINDOW_STYLE, int, int, int, int, winmdroot.Foundation.HWND, winmdroot.UI.WindowsAndMessaging.HMENU, winmdroot.Foundation.HINSTANCE, void*)' that could not be resolved

Verification

Rebuilding the supplied consumer with this branch's generator, XML docs enabled, and TreatWarningsAsErrors=true succeeds with zero warnings. Targeted generator, composition, COM, and CLI tests pass.

The regression tests check compiler diagnostics and XML documentation emission rather than exact generated documentation text, retaining guards that the referenced PCWSTR is reused and friendly overloads are generated. All 16 friendly-overload tests pass. Temporarily disabling the ambiguity fix reproduces CS1580/CS1574 in all four duplicate-type cases while the four controls pass; restoring the old PWSTR links triggers CS1574 in the extension-receiver case, and omitting parameter-documentation filtering triggers CS1572 for the removed SecurityDescriptorSize parameter. All temporary mutations were reverted.

[Jevan Saks (jevansaks)]

I am not fluent in compiler error codes so I don't offhand know what CS1580/CS1574 are. Can you update the PR description or issue report to include a minimal repro or output of the offending generated code?

[Sergio Pedri (Sergio0694)]

Jevan Saks (@jevansaks) I've updated the title for clarity and included the full error messages in the description.