google / google/xls

Suggested Documentation Changes to "DSLX Tutorial: enumerate and match expressions"

Open
#1,252 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
C++
Stars
1.9k
Forks
283
Avg merge
2d 10h
Merged PRs (30d)
135

Description

[doc link](https://google.github.io/xls/tutorials/prefix_scan/)

* General: The underlying example is a fairly complex way to introduce new language concepts

* Remove `DSLX` from the title to match other tutorials (or add `DSLX` to them)

* Add link to [dslx_reference/#match-expression](https://google.github.io/xls/dslx_reference/#match-expression)

* There's no direct link in the language reference for `enumerate`; add a link to [dslx_reference/#iterable-expression](https://google.github.io/xls/dslx_reference/#iterable-expression) and consider breaking it out as a first-class link target

* Add a link to [dslx_reference/#array-type](https://google.github.io/xls/dslx_reference/#array-type) to describe arrays, especially since array initialization with repeated values is non-intuitive

* Add link to [dslx_intro/prefix_scan_equality.x](https://github.com/google/xls/blob/main/xls/examples/dslx_intro/prefix_scan_equality.x), which doesn't actually compile :(

```
0019: for ((i, elem), (prior, count, result)): ((u32, u32), (u32, u3, u3[8]))
0020: in enumerate(x) {
~~~~~~~~~~~~~~~~~~~~~~~~~~~~^-^ ConversionError: iterable (enumerate(x)) must be bits-typed, constexpr, and its start must be less than or equal to its limit.
```

* Function prefix_scan_eq
* Enumerated Loop
* `Looping back to the prior let statement` is a bit confusing since we're talking about loops here, maybe `Referring` or `Looking back to the prior let statement` would be more clear

* A match expression
* Add a link to [dslx_reference/#match-expression](https://google.github.io/xls/dslx_reference/#match-expression)

* There's no language reference for how the `update` builtin function works

* In the `Following the loop body`, the loop initializer value in tutorial is -1, code uses 0xffffffff, change 1 to match the other

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.