Documentation update for reduce functions, swizzle

[sstangl]

Working through giving example documentation to every Simd function.

The major change in this patch is using doc macros to generate
type-specific examples for each function, using a visually-apparent type
constructor. This makes it feel nicer to have twelve separate
documentation entries for reduce_product(), for example.

There's quite a lot to go through. I'm hoping this introductory patch sets something of a style for examples. In general, I tried to copy the style of the std::vec::Vec documentation, which I think is quite good.

The doc-macros here look a bit crafty, but I think the documentation they generate is very readable. Some examples:

for reduce_sum, specialized on u64:

let v = u64x4::from_array([1, 2, 3, 4]);
assert_eq!(v.reduce_sum(), 10);

// SIMD integer addition is always wrapping
let v = u64x4::from_array([u64::MAX, 1, 0, 0]);
assert_eq!(v.reduce_sum(), u64::MIN);

it would have looked cleaner with i64x2, but unfortunately i8x2 doesn't exist.

for reduce_max, specialized on f32:

let v = f32x2::from_array([1., 2.]);
assert_eq!(v.reduce_max(), 2.);

// NaN values are skipped...
let v = f32x2::from_array([1., f32::NAN]);
assert_eq!(v.reduce_max(), 1.);

// ...unless all values are NaN
let v = f32x2::from_array([f32::NAN, f32::NAN]);
assert!(v.reduce_max().is_nan());

If this looks OK, happy to keep this going in future patches. I think compiling the beginners-guide.md into top-level crate documentation would also likely be helpful, because it would give explanations that other documentation could refer to, instead of repeating concepts.

[workingjubilee]

This is a very good improvement! I have only one note, which is mostly that there is not much need to take a cue from the existing content for phrasing.

In fact, while I realize it is currently everywhere, we want to reduce the presence of the "lanes" terminology over time because it is functionally "jargon". SIMD is a rather "specialty" subject, so we definitely don't have to go back to Programming 101, and certainly some users will be veteran SIMD programmers, thus familiar with it. But for others, like more mathematically-inclined users who may be coming from e.g. NumPy, and already feel in over their head with Rust, "lane" is mostly just Another Word, and ultimately SIMD is fine with borrowing terms that are mostly already used by Rust's arrays:

• Length
• Indices
• Elements, and especially
• "Elementwise"

That said, you don't have to actually do any changes to account for that yet, I am happy to merge this as-is, I just wanted to give you a heads up re: the incoming clobber, because I know how Writing Docs can get and you may have Specific Opinions on what changes to make as a result.