UnmanagedCallersOnlyAttribute.CallConvs and CallConvSuppressGCTransition

[filipnavara]

Type of issue

Missing information

Description

I find the documentation for UnmanagedCallersOnlyAttribute.CallConvs to be unintentionally misleading. It specifies that the valid values are CallConv* types. However, CallConvSuppressGCTransition is NOT valid value for the calling convention in this context - supressing GC transition is not allowed for reverse P/Invokes, which is the whole purpose of the UnmanagedCallersOnlyAttribute attribute. Moreover, the "See also" section specifically points to CallConvSuppressGCTransition documentation with a link to add to the confusion.

The documentation for CallConvSuppressGCTransition doesn't directly mention that it's only meant to be used for function pointers to unmanaged code. Instead it links to the description of the SuppressGCTransition attribute which lists the limitations for its use. Notably, I would be fine with the indirect link here if it was not for the documention of UnmanagedCallersOnlyAttribute.CallConvs. It's unreasonable to expect a documentation reader to go through two links and then read the remarks section to discover that some value combination is invalid.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.unmanagedcallersonlyattribute.callconvs?view=net-9.0#system-runtime-interopservices-unmanagedcallersonlyattribute-callconvs

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Runtime.InteropServices/UnmanagedCallersOnlyAttribute.xml

Document Version Independent Id

953bcf74-4793-6c98-5e89-c73dd0d748ff

Platform Id

436c4c22-d112-467c-323f-85c5547d49db

Article author

@dotnet-bot