google / google/xls

dslx_reference improvements

Open
#1,293 2 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

I'm going to record some things I noticed that need improvement:

- [x] In the [Precedence ](https://google.github.io/xls/dslx_reference/#operator-precedence)table, mis-rendered `||` and `|`
- https://github.com/google/xls/pull/1292
- [x] In the Precedence table, `>>>` should not be there because it does not exist
- https://github.com/google/xls/pull/1292
- [x] concatenate operator is missing from [Precedence](https://google.github.io/xls/dslx_reference/#operator-precedence). I believe it's the same precedence as `+` and `-` (confirmed below)
- https://github.com/google/xls/pull/1298
- [ ] `..` the range expression is missing from Precedence. I believe it's lower than everything else (lower than boolean or)
- [ ] `/` and `%` are in the [table ](https://google.github.io/xls/dslx_reference/#operator-precedence)but not mentioned in [binary expressions](https://google.github.io/xls/dslx_reference/#binary-expressions). Both operators are worth describing their precise semantics (e.g. is `%` the [remainder or the modulo function](https://stackoverflow.com/questions/13683563/whats-the-difference-between-mod-and-remainder)?)
- [ ] `as` is never introduced as a [binary expression ](https://google.github.io/xls/dslx_reference/#binary-expressions)or operator. It looks like this [section](https://google.github.io/xls/dslx_reference/#numerical-conversions) is about `as`. But I think the current way things are organized and described could be improved. E.g., `as` is clearly a binary expression as it takes two arguments. Why not make it a subsection under Binary Expressions? This suggestion also applies comparison operators and concatenation operator. Anything that's in the precedence table should probably be grouped as a unary or binary expression/operator.
- [x] `(...)`, the grouping expression, is never is never mentioned as an expression, nor is its precedence mentioned (I assume it's the highest precedence?)
- https://github.com/google/xls/pull/1298
- [ ] `true` and `false` are never introduced as a [bit type](https://google.github.io/xls/dslx_reference/#bit-type)
- [ ] 'expression statements' are never documented. E.g. `Foo();`
- [ ] `let` expressions are not expressions. They are statements. In the past they were expressions but they aren't now. Update the wording and move to the statement section.

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.