rust-lang / rust-lang/reference
Guidelines for referring to tools and compilers
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.6k
- Forks
- 607
- PR merge metrics
- PR metrics pending
Description
I think the authoring guide should have some guidelines for when, why, and how to refer to tools and implementations. In particular, things like rustc, clippy, cargo, rustfmt, miri, etc. The Reference occasionally refers to these things when it seems like that information would provide very helpful context, but there's a certain balance of doing that too little or too much. What are the guidelines for that balance?
There is a slightly different issue in https://github.com/rust-lang/reference/issues/2040 for implementation-specific guidelines.
Some examples from the Reference:
rustccurrently only allows theclippyandrustfmttool attributes. It has not yet been decided if the tool attribute space should be extensible (and if so, how).- The
featureattribute links to the Unstable book. - The description of user extensible
cfgvalues mentions the way to do that is viarustc --cfg. - The
testcfg is set viarustc --test. - Identifiers that start with an underscore are a convention to silence an unused warning in
rustc. - The dynamic and static C-runtime mentions
rustc -C target-feature=+crt-static - A note about the hazards of using
#[inline]and the relationship to howrustcworks. - How target-features and target-cpu's are related via
rustcoptions. - Note about how you can find the available lints in the lint attribute docs.
- Note about what
#[deprecated]does inrustc. - Defaults for
recursion_limitandtype_length_limit. - Mentions of certain hazards, like overflowing literals will generate a warning by
rustc. - Lots of documentation related to
#[link]needs to cross-link with therustcdocs. - The behavior of unwinding across nounwind abi uses an illegal instruction in
rustc. - An explanation of the requirement to use
extern alloc;due to the way things work. - How to write a proc-macro with Cargo.
- Note about security concerns of proc-macros.
- Source files discuss filesystems specifically, but in theory there could be other ways that source is loaded. How
rustc-specific is that?
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 with the authoring guide and review the listed Reference examples involving rustc, Cargo, Clippy, rustfmt, and Miri. Identify where tool or implementation context helps readers and where it adds unnecessary coupling. Done means the authoring guide contains agreed guidelines for when, why, and how these tools should be referenced, distinct from implementation-specific guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100