rust-lang / rust-lang/reference

Guidelines for referring to tools and compilers

Open
#2,043 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Authoring guide Meta
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:

  • rustc currently only allows the clippy and rustfmt tool attributes. It has not yet been decided if the tool attribute space should be extensible (and if so, how).
  • The feature attribute links to the Unstable book.
  • The description of user extensible cfg values mentions the way to do that is via rustc --cfg.
  • The test cfg is set via rustc --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 how rustc works.
  • How target-features and target-cpu's are related via rustc options.
  • Note about how you can find the available lints in the lint attribute docs.
  • Note about what #[deprecated] does in rustc.
  • Defaults for recursion_limit and type_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 the rustc docs.
  • 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.