dotnet / dotnet/dotnet-api-docs

UnmanagedCallersOnlyAttribute.CallConvs and CallConvSuppressGCTransition

Offen
#11,642 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area-System.Runtime.InteropServices untriaged
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

Beitragsleitfaden öffnen

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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.