rust-lang / rust-lang/reference
Normalize descriptions of syntax
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.6k
- Forks
- 607
- PR merge metrics
- PR metrics pending
Description
We have inconsistent uses of terminology for describing syntax. I've seen at least three:
- X is written as...
- X consists of...
- X is denoted with...
We should pick a single style, and use it consistently.
It doesn't have to be one of the above forms. I feel like we could be more explicit with the form:
- The syntax of X is...
For example, using the type cast expression:
The syntax of a type cast expression is an operand, the keyword
as, and finally a type.
cc @ehuss for opinions.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Search the Rust Reference for the listed syntax-description forms, starting with the type cast expression example and nearby syntax sections. Record the occurrences that need normalization, apply the chosen wording consistently, and verify the affected reference pages read uniformly.
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
- Mostly clear
- Newbie friendliness
- 45/100