rust-lang / rust-lang/reference
Consider a normative references chapter
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.6k
- Forks
- 607
- PR merge metrics
- PR metrics pending
Description
ISO standards have a mandatory Normative References chapter. I considered this a lot in the past, but never got around to adding it. There's not a lot that would necessarily be listed, but if we really want to be precise about how things work, it would cover those bases.
Some examples:
- The specific Unicode standard is already documented in the identifiers chapter, but could/should also be included in the references.
- The specific C specification we are working against. For example, things like C-variadics refer to specific C features without specifying which C standard.
- Unwinding refers to C++ without referring to anything specific (I'm not sure if this necessary, see this thread).
- Inline assembly refers to LLVM, and using its syntax, without specifying which LLVM.
- The ABI list refers to specific documentation and standards.
I don't know what exactly makes sense to include. And I'm not sure how valuable it would be, and would it be worth the maintenance cost.
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
Start by reviewing the identifiers, unwinding, inline assembly, and ABI chapters, along with the standards and documentation they currently mention. Determine which Unicode, C, C++, LLVM, ABI, and other references are specific enough to include and whether their maintenance cost is justified. Done means documenting an agreed normative references scope, or recording why the chapter should not be added.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, cpp, rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100