dotnet / dotnet/dotnet-api-docs

Vector256.Create() doesn't document that it corresponds to _mm256_setr_epiN (set reverse)

Offen
#8,288 3 Kommentare 2 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area-System.Runtime.Intrinsics documentation help wanted Pri3
Vorherrschende Sprache
C#
Sterne
949
Forks
1.7k
Ø Merge
2 T. 19 Std.
Gemergte PRs (30 T.)
52

Beschreibung

### Description

(This also matters for `Vector128.Create()` and any other similar methods)

`Vector256.Create()` is a helper function that, on Intel/AVX2, corresponds to `_mm256_setr_epiN` where `N` is 8, 16, 32, 64. When the .NET intrinsics were designed, they were intentionally done such that the order of these parameters was reversed. This makes sense, but it causes pain when porting code from C/C++. I think this can be improved with a very simple addition to the doc comments (and therefore the Intellisense tooltips).

All of the `Avx2` method intrinsics have a _very_ helpful note in the doc comment (and therefore Intellisense tooltip) specifying which intrinsic and which instruction they line up with, e.g.

image

However, the `Create()` methods do not. Since these correspond to `setr` instead of `set`, the order that is needed is reversed from what we see in C/C++ code.

This just burned a bunch of my time, and I know it bit @EgorBo at some point too and he lost an hour to it. I just ported 1300 lines of vectorized instrinsics code over to C# and everything is _almost_ right, but my validation code was catching some off-by-1 errors.

I know these are supposed to be instruction-set agnostic, but they really need to list which intrinsic they line up with, even if they have to list it for every instruction set (i.o.w. AVX and ARM). I was going line-by-line, validating all of my instructions to make sure that they matched up, and everything does, until I realized "wait, those Create() methods are backwards from the set() intrinsics, right?" When writing or porting vectorized/intrinsics code, finding these errors is often a needle-in-a-haystack problem, and simple things like helpful doc comments go a very long way toward shortening the time that's needed to debug and these. (the existing doc comments on the intrinsics are _extremely_ helpful in that regard)

image

Put another way, these are _helper_ methods. They should be _helpful_ ... they are currently _unhelpful_ :)

EDIT: Apparently the docs pages on MSDN _do_ list this information in the Remarks section. However, this is not useful enough because it does not show up in the IntelliSense popups in Visual Studio:

image

### Reproduction Steps

Port some C++ intrinsics code that uses `_mm256_set_epiN` and/or `_mm128_set_epiN` over to C#

### Expected behavior

The doc pages, doc comments, and IntelliSense popups are helpful at every step of the process

### Actual behavior

The doc pages, doc comments, and IntelliSense popups are helpful at every step of the process _except when it comes to `_mm256_set_epiN` / `Vector256.Create()`, and `_mm128_set_epiN` / `Vector128.Create()`_

### Regression?

Not a regression

### Known Workarounds

Just reverse the order of the parameters. There's no code bug here, just a docs bug (IMO).

### Configuration

_No response_

### Other information

_No response_

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne damit, die API-Dokumentationskommentare für Vector256.Create und Vector128.Create zu finden, und vergleiche dann deren auf IntelliSense ausgerichtete Hinweise mit den vorhandenen Kommentaren zu den Avx2-Intrinsics. Aktualisiere die relevanten Kommentare, um die setr-Entsprechung und die umgekehrte Parameterreihenfolge zu erklären; abgeschlossen, wenn die Informationen in den Dokumentationskommentaren und IntelliSense-Tooltips erscheinen.

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
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

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