Description
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.
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)
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:
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