Suggestion for improving documentation

[chinwobble]

Hi I want to help improve the documentation for helping beginners (like myself) to understand how each operation works and when they would be useful.
Currently the documentation is very terse and this is good if you are an expert that just needs a reminder.
For beginners, the documentation can benefit from a more concrete example of what each operation does.

A good reference is rxjs documentation.
Each rxjs operation has an associated diagram and example code. https://rxjs.dev/api/index/function/auditTime

Proposed structure:

• Operation Name
  • describe what it does
  • What situation would this operation be useful
  • potential diagram illustrating with some standard vector
  • example code with concrete inputs and outputs

For the diagram and example code maybe we can standardise the documentation on something like AVX2 (256 bit vector) and uint8_t.

example:

V Dup128VecFromValues(D d, T t0, .., T tK): Creates a vector from K+1 values, broadcasted to each 128-bit block if Lanes(d) >= 16/sizeof(T) is true, where K is 16/sizeof(T) - 1.
Dup128VecFromValues returns the following values in each 128-bit block of the result, with t0 in the least-significant (lowest-indexed) lane of each 128-bit block and tK in the most-significant (highest-indexed) lane of each 128-bit block: {t0, t1, ..., tK}
Why is this useful???

const ScalableTag<int32_t> d;
const size_t N = Lanes(d);
const auto v = Dup128VecFromValues(d, 100, 200, 300, 400);
Print(d2, "Dup128VecFromValues", v, 0, N);
// output
// i32x8 Dup128VecFromValues [0+ ->]:
//  100,200,300,400,100,200,300,400,

[jan-wassenberg]

Hi, thanks for reaching out. This sounds like a great idea :)
Some other prior art for inspiration:
https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html has pseudocode - not particularly elegant nor formally precise, but still helpful.
https://www.officedaytime.com/simd512e/ has excellent diagrams after clicking on an instruction.

Were you thinking of a markdown file in the g3doc directory?
I'd recommend avoiding actual images and seeing how far we get with markdown features such as tables.

256 bit sounds reasonable, but u8 is going to lead to many many elements. How about we use u64/f64 wherever supported to reduce the number of values we have to show?