rust-lang/portable-simd#272: Standardize documentation for SIMD vector and mask types

This is a documentation-only patch that standardizes the presentation of vector types like `u32x4` and mask types like `mask32x16`.

The reasoning behind the patch was as follows:
1. Standardized terminology should be preferred, so `element` instead of `value` and `SIMD vector` instead of `vector`. These terms appear in the rest of the documentation and tutorials.
2. Try to avoid situations where two numbers are next to each other. So `16 elements of 32 bits` instead of `16 32-bit elements`.
4. Try to anticipate what readers are looking for -- so state the full bit-width directly.

### Vector Types
- Before: Vector of 32 `i8` values
- After: A 256-bit SIMD vector with 32 elements of type `i8`.

### Mask Types
- Before: Vector of 16 16-bit masks
- After: A mask for SIMD vectors with 16 elements of 32 bits.

Author: workingjubilee

crates/core_simd/src/masks.rs

@@ -77,6 +77,8 @@ impl_element! { isize }
 
 /// A SIMD vector mask for `LANES` elements of width specified by `Element`.
 ///
+/// Masks represent boolean inclusion/exclusion on a per-lane basis.
+///
 /// The layout of this type is unspecified.
 #[repr(transparent)]
 pub struct Mask<T, const LANES: usize>(mask_impl::Mask<T, LANES>)
@@ -507,58 +509,58 @@ where
     }
 }
 
-/// Vector of eight 8-bit masks
+/// A mask for SIMD vectors with eight elements of 8 bits.
 pub type mask8x8 = Mask<i8, 8>;
 
-/// Vector of 16 8-bit masks
+/// A mask for SIMD vectors with 16 elements of 8 bits.
 pub type mask8x16 = Mask<i8, 16>;
 
-/// Vector of 32 8-bit masks
+/// A mask for SIMD vectors with 32 elements of 8 bits.
 pub type mask8x32 = Mask<i8, 32>;
 
-/// Vector of 16 8-bit masks
+/// A mask for SIMD vectors with 64 elements of 8 bits.
 pub type mask8x64 = Mask<i8, 64>;
 
-/// Vector of four 16-bit masks
+/// A mask for SIMD vectors with four elements of 16 bits.
 pub type mask16x4 = Mask<i16, 4>;
 
-/// Vector of eight 16-bit masks
+/// A mask for SIMD vectors with eight elements of 16 bits.
 pub type mask16x8 = Mask<i16, 8>;
 
-/// Vector of 16 16-bit masks
+/// A mask for SIMD vectors with 16 elements of 16 bits.
 pub type mask16x16 = Mask<i16, 16>;
 
-/// Vector of 32 16-bit masks
+/// A mask for SIMD vectors with 32 elements of 16 bits.
 pub type mask16x32 = Mask<i16, 32>;
 
-/// Vector of two 32-bit masks
+/// A mask for SIMD vectors with two elements of 32 bits.
 pub type mask32x2 = Mask<i32, 2>;
 
-/// Vector of four 32-bit masks
+/// A mask for SIMD vectors with four elements of 32 bits.
 pub type mask32x4 = Mask<i32, 4>;
 
-/// Vector of eight 32-bit masks
+/// A mask for SIMD vectors with eight elements of 32 bits.
 pub type mask32x8 = Mask<i32, 8>;
 
-/// Vector of 16 32-bit masks
+/// A mask for SIMD vectors with 16 elements of 32 bits.
 pub type mask32x16 = Mask<i32, 16>;
 
-/// Vector of two 64-bit masks
+/// A mask for SIMD vectors with two elements of 64 bits.
 pub type mask64x2 = Mask<i64, 2>;
 
-/// Vector of four 64-bit masks
+/// A mask for SIMD vectors with four elements of 64 bits.
 pub type mask64x4 = Mask<i64, 4>;
 
-/// Vector of eight 64-bit masks
+/// A mask for SIMD vectors with eight elements of 64 bits.
 pub type mask64x8 = Mask<i64, 8>;
 
-/// Vector of two pointer-width masks
+/// A mask for SIMD vectors with two elements of pointer width.
 pub type masksizex2 = Mask<isize, 2>;
 
-/// Vector of four pointer-width masks
+/// A mask for SIMD vectors with four elements of pointer width.
 pub type masksizex4 = Mask<isize, 4>;
 
-/// Vector of eight pointer-width masks
+/// A mask for SIMD vectors with eight elements of pointer width.
 pub type masksizex8 = Mask<isize, 8>;
 
 macro_rules! impl_from {

crates/core_simd/src/vector/float.rs

@@ -177,23 +177,23 @@ macro_rules! impl_float_vector {
 impl_float_vector! { f32, u32, i32 }
 impl_float_vector! { f64, u64, i64 }
 
-/// Vector of two `f32` values
+/// A 64-bit SIMD vector with two elements of type `f32`.
 pub type f32x2 = Simd<f32, 2>;
 
-/// Vector of four `f32` values
+/// A 128-bit SIMD vector with four elements of type `f32`.
 pub type f32x4 = Simd<f32, 4>;
 
-/// Vector of eight `f32` values
+/// A 256-bit SIMD vector with eight elements of type `f32`.
 pub type f32x8 = Simd<f32, 8>;
 
-/// Vector of 16 `f32` values
+/// A 512-bit SIMD vector with 16 elements of type `f32`.
 pub type f32x16 = Simd<f32, 16>;
 
-/// Vector of two `f64` values
+/// A 128-bit SIMD vector with two elements of type `f64`.
 pub type f64x2 = Simd<f64, 2>;
 
-/// Vector of four `f64` values
+/// A 256-bit SIMD vector with four elements of type `f64`.
 pub type f64x4 = Simd<f64, 4>;
 
-/// Vector of eight `f64` values
+/// A 512-bit SIMD vector with eight elements of type `f64`.
 pub type f64x8 = Simd<f64, 8>;

crates/core_simd/src/vector/int.rs

@@ -42,62 +42,62 @@ impl_integer_vector! { i32 }
 impl_integer_vector! { i64 }
 impl_integer_vector! { i8 }
 
-/// Vector of two `isize` values
+/// A SIMD vector with two elements of type `isize`.
 pub type isizex2 = Simd<isize, 2>;
 
-/// Vector of four `isize` values
+/// A SIMD vector with four elements of type `isize`.
 pub type isizex4 = Simd<isize, 4>;
 
-/// Vector of eight `isize` values
+/// A SIMD vector with eight elements of type `isize`.
 pub type isizex8 = Simd<isize, 8>;
 
-/// Vector of two `i16` values
+/// A 32-bit SIMD vector with two elements of type `i16`.
 pub type i16x2 = Simd<i16, 2>;
 
-/// Vector of four `i16` values
+/// A 64-bit SIMD vector with four elements of type `i16`.
 pub type i16x4 = Simd<i16, 4>;
 
-/// Vector of eight `i16` values
+/// A 128-bit SIMD vector with eight elements of type `i16`.
 pub type i16x8 = Simd<i16, 8>;
 
-/// Vector of 16 `i16` values
+/// A 256-bit SIMD vector with 16 elements of type `i16`.
 pub type i16x16 = Simd<i16, 16>;
 
-/// Vector of 32 `i16` values
+/// A 512-bit SIMD vector with 32 elements of type `i16`.
 pub type i16x32 = Simd<i16, 32>;
 
-/// Vector of two `i32` values
+/// A 64-bit SIMD vector with two elements of type `i32`.
 pub type i32x2 = Simd<i32, 2>;
 
-/// Vector of four `i32` values
+/// A 128-bit SIMD vector with four elements of type `i32`.
 pub type i32x4 = Simd<i32, 4>;
 
-/// Vector of eight `i32` values
+/// A 256-bit SIMD vector with eight elements of type `i32`.
 pub type i32x8 = Simd<i32, 8>;
 
-/// Vector of 16 `i32` values
+/// A 512-bit SIMD vector with 16 elements of type `i32`.
 pub type i32x16 = Simd<i32, 16>;
 
-/// Vector of two `i64` values
+/// A 128-bit SIMD vector with two elements of type `i64`.
 pub type i64x2 = Simd<i64, 2>;
 
-/// Vector of four `i64` values
+/// A 256-bit SIMD vector with four elements of type `i64`.
 pub type i64x4 = Simd<i64, 4>;
 
-/// Vector of eight `i64` values
+/// A 512-bit SIMD vector with eight elements of type `i64`.
 pub type i64x8 = Simd<i64, 8>;
 
-/// Vector of four `i8` values
+/// A 32-bit SIMD vector with four elements of type `i8`.
 pub type i8x4 = Simd<i8, 4>;
 
-/// Vector of eight `i8` values
+/// A 64-bit SIMD vector with eight elements of type `i8`.
 pub type i8x8 = Simd<i8, 8>;
 
-/// Vector of 16 `i8` values
+/// A 128-bit SIMD vector with 16 elements of type `i8`.
 pub type i8x16 = Simd<i8, 16>;
 
-/// Vector of 32 `i8` values
+/// A 256-bit SIMD vector with 32 elements of type `i8`.
 pub type i8x32 = Simd<i8, 32>;
 
-/// Vector of 64 `i8` values
+/// A 512-bit SIMD vector with 64 elements of type `i8`.
 pub type i8x64 = Simd<i8, 64>;

crates/core_simd/src/vector/uint.rs

@@ -2,62 +2,62 @@
 
 use crate::simd::Simd;
 
-/// Vector of two `usize` values
+/// A SIMD vector with two elements of type `usize`.
 pub type usizex2 = Simd<usize, 2>;
 
-/// Vector of four `usize` values
+/// A SIMD vector with four elements of type `usize`.
 pub type usizex4 = Simd<usize, 4>;
 
-/// Vector of eight `usize` values
+/// A SIMD vector with eight elements of type `usize`.
 pub type usizex8 = Simd<usize, 8>;
 
-/// Vector of two `u16` values
+/// A 32-bit SIMD vector with two elements of type `u16`.
 pub type u16x2 = Simd<u16, 2>;
 
-/// Vector of four `u16` values
+/// A 64-bit SIMD vector with four elements of type `u16`.
 pub type u16x4 = Simd<u16, 4>;
 
-/// Vector of eight `u16` values
+/// A 128-bit SIMD vector with eight elements of type `u16`.
 pub type u16x8 = Simd<u16, 8>;
 
-/// Vector of 16 `u16` values
+/// A 256-bit SIMD vector with 16 elements of type `u16`.
 pub type u16x16 = Simd<u16, 16>;
 
-/// Vector of 32 `u16` values
+/// A 512-bit SIMD vector with 32 elements of type `u16`.
 pub type u16x32 = Simd<u16, 32>;
 
-/// Vector of two `u32` values
+/// A 64-bit SIMD vector with two elements of type `u32`.
 pub type u32x2 = Simd<u32, 2>;
 
-/// Vector of four `u32` values
+/// A 128-bit SIMD vector with four elements of type `u32`.
 pub type u32x4 = Simd<u32, 4>;
 
-/// Vector of eight `u32` values
+/// A 256-bit SIMD vector with eight elements of type `u32`.
 pub type u32x8 = Simd<u32, 8>;
 
-/// Vector of 16 `u32` values
+/// A 512-bit SIMD vector with 16 elements of type `u32`.
 pub type u32x16 = Simd<u32, 16>;
 
-/// Vector of two `u64` values
+/// A 128-bit SIMD vector with two elements of type `u64`.
 pub type u64x2 = Simd<u64, 2>;
 
-/// Vector of four `u64` values
+/// A 256-bit SIMD vector with four elements of type `u64`.
 pub type u64x4 = Simd<u64, 4>;
 
-/// Vector of eight `u64` values
+/// A 512-bit SIMD vector with eight elements of type `u64`.
 pub type u64x8 = Simd<u64, 8>;
 
-/// Vector of four `u8` values
+/// A 32-bit SIMD vector with four elements of type `u8`.
 pub type u8x4 = Simd<u8, 4>;
 
-/// Vector of eight `u8` values
+/// A 64-bit SIMD vector with eight elements of type `u8`.
 pub type u8x8 = Simd<u8, 8>;
 
-/// Vector of 16 `u8` values
+/// A 128-bit SIMD vector with 16 elements of type `u8`.
 pub type u8x16 = Simd<u8, 16>;
 
-/// Vector of 32 `u8` values
+/// A 256-bit SIMD vector with 32 elements of type `u8`.
 pub type u8x32 = Simd<u8, 32>;
 
-/// Vector of 64 `u8` values
+/// A 512-bit SIMD vector with 64 elements of type `u8`.
 pub type u8x64 = Simd<u8, 64>;