# Expand the Rust Reference to cover more aspects of the Rust language

| Metadata | |
| :-- | :-- |
| Point of contact | @joshtriplett |
| Teams | <!-- TEAMS WITH ASKS --> |
| Task owners | <!-- TASK OWNERS --> |
| Status | Proposed |
| Zulip channel | [#t-spec][channel] |
| Tracking issue | [rust-lang/rust-project-goals#NNN] |

[channel]: https://rust-lang.zulipchat.com/#narrow/channel/399173-t-spec

## Summary

The Rust Reference (https://doc.rust-lang.org/nightly/reference/) describes and
documents the Rust language. The Reference has coverage of many areas of Rust
already, and it has been integrated into language evolution processes, so that
new changes to the language get corresponding updates to the Reference.
However, there are some remaining gaps in the Reference's existing coverage of
Rust.

This project goal proposes to write new chapters for the Reference to fill
these gaps, making its coverage of Rust more comprehensive. This project goal
also proposes to provide additional review bandwidth for other changes, to
ensure that the new material does not overwhelm existing review capacity.

## Motivation

The Rust Reference is one of the core pieces of documentation for Rust. It
serves as documentation for users and implementers alike. The Reference should,
ideally, describe all aspects of the Rust language comprehensively. It is
easier to contribute changes to existing material than large swaths of new
material; the latter is a larger commitment. Thus, this project goal will
coordinate the efforts of several prospective contributors (who have already
been identified and lined up) to write, contribute, and merge new material for
the Reference.

Writing new material for the Reference does not suffice to get it merged,
however. Each change to the Reference requires review and approval, which
sometimes requires calling in additional expertise, and can require more and
scarcer resources. This project goal serves to request such review resources,
and additionally to coordinate contribution of additional review resources in
other areas to share the overall review load, in an effort to alleviate this
and not put as much additional load on existing contributors.

### The status quo

We consulted multiple experts on the Rust Reference, and based on that and on
analysis of the current Rust Reference, some of the key areas of Rust that the
Reference doesn't fully specify (and in some cases no documentation fully
specifies) are:

- The behavior of type inference, including both when the language can infer
types and the boundaries and limitations of when it cannot.
- The trait solver (up to date with the new solver work by @lcnr).
- More details on macros and expansion, in general. Macros-by-example
(declarative `macro_rules!` macros) are mostly covered, but not things like
the exact behavior of proc macros and the general process such as cfg
pruning.
- Name resolution: the process by which the Rust compiler resolves a name used
in Rust code, including methods of traits, and items imported from various
modules in various crates. Name resolution includes various extensions and
special cases that have been added over the years, and the reference should
document those and their behavior.
- Completing documentation of const eval.

#### Out of scope

Other items, which are out of the scope of this project goal:

- The behavior of the borrow checker. This is extensive work that has been the
subject of PhD theses. There have been multiple attempts to document and
bound the behavior of the borrow checker, the latest of which is Tree Borrows
( https://www.ralfj.de/blog/2023/06/02/tree-borrows.html ) by Ralf Jung, a
successor to the previous Stacked Borrows model. Specifying this will also
carefully distinguishing between description of the current behavior and
bounds on future behavior, as the borrow checker likely will improve further
in the future.
- The operational semantics of the Rust language, which includes the work
formerly described as "unsafe code guidelines". This has been the focus of
the opsem team (https://github.com/rust-lang/opsem-team).

Both of these have substantial efforts already working on them. In some cases,
this work is as much about determining and negotiating the correct semantics as
documenting them. These two areas have been the work of years and are unlikely
to get completed or substantively accelerated in the goal period.

### The next 6 months

We propose to have a team of established Rust developers working on different
new chapters of the Reference, writing and contributing material for those
chapters. Along the way, we expect to make various other contributions based on
what turns up during the project period while re-reviewing existing material.
We hope to substantially close the gap between the Reference and the Rust language.

The developers working on this project goal have expert-level knowledge of
multiple areas of Rust, and in several cases, directly worked on the portions
of Rust that need documenting.

We're expecting to coordinate new contributions from (at a minimum) @lcnr,
@jackh726, @Amanieu, @GuillaumeGomez, and @yaahc.

Resources available for review and mentoring include @joshtriplett, @lcnr,
@jackh726, @Amanieu, @GuillaumeGomez, @m-ou-se, @petrochenkov, and @yaahc.

### The "shiny future" we are working towards

We hope to continue providing ongoing support for reference updates in our
areas of expertise, as well as making it easier for others to make ongoing
contributions by providing a starting point. While we don't expect the
Reference to ever be "done" (much as the Rust language will not be), we hope to
substantially close the gap between the Reference and the language,

In the future, we hope that the reference will include full and complete
documentation for all parts of the Rust language, including the borrow checker
and the operational semantics.

## Design axioms

The following [design axioms][da] apply:
* Something being documented in the Rust Reference does not prevent it from changing, and does not introduce new stability guarantees that weren't already present.
* Corollary: Don't worry about "over-documenting" Rust; doing so does not over-constrain Rust or prevent it from evolving and fixing bugs.
* Corollary: Attempting to document something may result in discovering issues with the way it works. If that happens, report it, but don't let attempting to fix it block documenting its current behavior.

[da]: ../about/design_axioms.md

## Ownership and team asks

**Owner:** @joshtriplett, in his capacity as `t-lang` and `t-spec` team member,
will lead this project goal.

Specific task owners for reference chapters are advance predictions, but people may end up trading off on work.

| Task | Owner(s) or team(s) | Notes |
|------------------------------------|--------------------------------|---------------------------------|
| Discussion and moral support | ![Team][] [spec][] | |
| New reference chapters | @lcnr, @jackh726, @Amanieu, @GuillaumeGomez, @yaahc | |
| Standard reviews | @joshtriplett, @lcnr, @jackh726, @Amanieu, @GuillaumeGomez, @m-ou-se, @petrochenkov, @yaahc | |
| Standard reviews | ![Team][] [spec][] | |

## Frequently asked questions