google / google/highway

Suggestion for improving documentation

Open
#2,399 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
5.8k
Forks
471
Avg merge
1d 6h
Merged PRs (30d)
81

Description

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???

```cpp
const ScalableTag 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,
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.