Consider #[deprecated] on two Intel intrinsic APIs

[raphaelcohn]

Intel managed to misname two intrinsic APIs for AVX: _mm256_slli_si256 and _mm256_srli_si256, and then aliased the newer names _mm256_bslli_epi128 and _mm256_bsrli_epi128 to them. The former names are confusing, as they don't actually do 256-bit left or right shifts; they do 128-bit shifts on two 128-bit lanes.

I got caught out by this just now. In Rust, could we use the #[deprecated] syntax to warn users and point them to their (slightly) better named twins _mm256_bslli_epi128 and _mm256_bsrli_epi128.

Here's an Intel conversation were they change name: https://community.intel.com/t5/Intel-C-Compiler/mm256-slli-si256-and-mm256-srli-si256/td-p/820224.

[Lokathor]

we could easily change the rustdoc, but i personally wouldn't want to see it marked deprecated.

[raphaelcohn]

Changing the rustdoc would be a good idea. However, in code that is maintained over many years, the only documentation is code itself; that is the advantage of an attribute such as deprecated. Is your aversion that deprecated is intended purely for Rust language items that were, for want of a better word, 'mistakes', or that Intel themselves aren't clear?

[Lokathor]

The core::arch goal is basically that whatever the vendor offers, we will attempt to provide that interface. So until Intel stops listing a function in their intrinsics guide, we will provide it as best we can.

[bjorn3]

Didn't they effectively deprecate (but not remove) the old name? Matching whatever the vendor does in this case would be marking it as deprecated in stdarch too.

[CryZe]

Why did you close this? I don't think this change happened yet?!