search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
725 stars 1.56k forks source link

IRawElementProviderHwndOverride is documented as implementing IRawElementProviderSimple even though it doesn't #4257

Open hughbe opened 4 years ago

hughbe commented 4 years ago

See https://github.com/dotnet/winforms/pull/3231#discussion_r427133765

IRawElementProviderHwndOverride inherits from IUnknown only: https://github.com/tpn/winsdk-10/blob/9b69fd26ac0c7d0b83d378dba01080e93349c2ed/Include/10.0.10240.0/um/UIAutomationCore.idl#L401-L410

//
//  IRawElementProviderHwndOverride
//
[object, uuid(1d5df27c-8947-4425-b8d9-79787bb460b8), pointer_default(unique)]
interface IRawElementProviderHwndOverride : IUnknown
{
    HRESULT GetOverrideProviderForHwnd(
        [in] HWND hwnd,
        [out, retval] IRawElementProviderSimple ** pRetVal);
}

In https://docs.microsoft.com/en-us/windows/win32/api/uiautomationcore/nn-uiautomationcore-irawelementproviderhwndoverride

The IRawElementProviderHwndOverride interface inherits from the IUnknown interface. IRawElementProviderHwndOverride also has these types of members:

However, the .NET API docs https://docs.microsoft.com/en-us/dotnet/api/system.windows.automation.provider.irawelementproviderhwndoverride?view=netcore-3.1 say that it implements IRawElementProviderSimple.

This may be a bug in the implementation of IRawElementProviderSimple in UIAutomationProvider.dll.

I don't know if this can be changed because that could be source breaking. However, we should definitely document the fact that the class shouldn't actually inherit from IRawElementProviderSimple.

This is especially relevant because the documentation is in conflict between win32 and .NET

weltkante commented 4 years ago

I don't think this needs any implementation change, its not technically wrong, interface inheritance in managed and native code means different things. The way its done just forces implementing classes to implement both interfaces while the native API allows implementing them individually.

The point is that its easy to mix up the docs of native/managed interfaces since they are sharing the same name and GUID and all. It might be worth highlighting the differences to avoid people making mistakes.