rust-lang / rust-lang/reference

Simplify syntax diagrams

Open
#1,805 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-grammar
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

Coming back to the off-topic point in #1798: Some of the syntax diagrams can be simplified quite a bit by removing superfluous elements. There are basically two ways to solve this:

  • Implement an optimizer that takes the grammar's AST and performs the simplification automatically. Such as here.
  • Manually take care not to introduce superfluous elements in the grammar rules themselves. There is a conflict of goals here, as the rules become more compact/nested. That is, the visual representation becomes easier to follow at the cost of the textual representation becoming harder to understand.

See #1798 on what this does to the syntax. Do you fancy a PR for the either of those options? The second one is obviously much more simple to do.

Image

Image

Image

Image

Image

Image

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the context in #1798 and comparing the six attached syntax diagrams with their grammar rules. Review the two proposed approaches, including the optimizer example in lowering.rs, then determine which scope is appropriate; done means the superfluous diagram elements are removed without changing the documented syntax.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.