dotnet / dotnet/dotnet-api-docs
UnmanagedCallersOnlyAttribute.CallConvs and CallConvSuppressGCTransition
- Vorherrschende Sprache
- C#
- Sterne
- 950
- Forks
- 1.7k
- Ø Merge
- 2 T. 19 Std.
- Gemergte PRs (30 T.)
- 52
Beschreibung
### 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
Beitragsleitfaden
Rechercherichtung
Beginne mit xml/System.Runtime.InteropServices/UnmanagedCallersOnlyAttribute.xml und überprüfe die Dokumentation zu CallConvs zusammen mit der verknüpften Dokumentation zu CallConvSuppressGCTransition. Aktualisiere die Formulierung und den Querverweis so, dass die gültige Verwendung und die Einschränkung klar sind, ohne dass Leser mehreren Links folgen müssen; abgeschlossen ist die Aufgabe, wenn die API-Dokumentation nicht mehr impliziert, dass jeder CallConv*-Typ hier gültig ist.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- csharp
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 2/5
- Geschätzter Aufwand
- 1-3 Stunden
- Aktivitätsstatus
- Veraltet
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 48/100