Overview

Tracking issue for RFC #1636. Let's make the reference a reliable resource for all Rustaceans! :tada: This might seem intimidating, but the reality is that if we just chip away at it together, we'll be done in no time!

I'm going to be updating this parent issue with a master list of items that need to be documented in the reference as I find them. Quoting the RFC text:

Updating the reference should proceed stepwise:

1. Begin by adding an appendix in the reference with links to all accepted RFCs which have been implemented but are not yet referenced in the documentation.
2. As the reference material is written for each of those RFC features, remove it from that appendix.

Note that step 1 should be fairly straightforward; the main issue will be assembling the list of accepted-and-implemented-but-undocumented RFCs. (Also, any RFCs accepted before RFC 1636 but not yet stabilized should presumably be documented under the rules it establishes, but if I'm wrong about that, someone should let me know and I'll include them as well.)

Also, a pre-emptive apology for the scale of this issue description. We have let things get into a rough spot. (I plan to create documentation issues for each of the required items below once this list is completed, so this thread doesn't become completely unmanageable.)

Status: Last updated May 13, 2017, now processing a copy of @Eh2406's wonderful gist based on @matthewjasper's fork here.

"How Can I Help?"

For right now, since you can't submit updates to the issue directly, there are two major ways you can help:

1. Write documentation. For the RFCs already triaged and filed under the major section C. Documentation Needed and specifically the subsection 2. Write reference material for undocumented, implemented, stabilized RFC features below, you can open a pull request and reference this issue in its description. I'll keep an eye out for inbound links here and add those links to the relevant items, and once they're merged, we'll mark that item as done.

2. Triage issues. Work the gist where I'm tracking the triaged-state, specifically looking at the Not Reviewed at All and Stabilized, Not Reviewed sections and evaluating whether they're documented or not. You can fork the gist and I will keep an eye out, checking roughly daily, for any changes to merge back into that document. (Do take a look at what others may have forked it so you don't duplicate work needlessly!) I'll then pull those over into this master issue.

   When working through those, if you determine that they're already documented, please leave a note (and link!) on your copy of the gist as to where so I can link it in this document. That dramatically decreases the time it takes me to confirm it—I double-check all of these.

A. Tracking

(This section will go away entirely once all of the RFCs have been flagged for documenting or marked documentation-not-needed here.)

RFCs reviewed

Currently: 115/301

RFCs unreviewed

B. Status unclear

Some of these are still in-flight; and some of them are just the kind of thing that I don't even fully grok yet well enough to see if they're documented. For these, unchecked means "status unknown"; checked means "status known and added to the latter bits appropriately."

• [ ] #0019: Opt-in built-in traits (OIBITs)
  • status query

C. Documentation needed

0. Accepted, not-yet-stabilized, undocumented RFCs

0.1. Document implemented, unstable RFCs

These should be considered the highest priority for documentation, as these are issues which fall under the rest of the rules of [RFC #1636], in that they need to be documented before stabilization. (That will presumably just happen before stabilizing as usual, but I'm including them here for completeness.)

• [ ] #0086 plugin-registrar API
• [ ] #0202: subslice syntax change -- implemented here, not stabilized; see discussion of [#0405] below under C.0.2.
• [ ] #1131: Add an expect intrinsic
• [ ] #1358: repr_align – implementation is in-progress, not yet landed on nightly
• [x] #1624: loop_break_value
• [x] #1665: Windows subsystem support

0.2. Track accepted, not-yet-implemented or implementation-in-progress, undocumented RFCs

These will eventually require documentation, but as they aren't even (fully) implemented yet, there is no urgency here.

• [ ] #0066: Better temporary lifetimes – tracking issue
• [x] #0495: Array/slice/subslice pattern adjustments – tracking issue
• [ ] #0803: type ascription on expressions – tracking issue
• [ ] #1199: SIMD infrastructure (Note: this is stalled; it may eventually be superceded by a further RFC.)
• [ ] #1214: Projections, lifetimes, and well-formed-ness
• [ ] #1398: Standard and custom allocator API – tracking issue
• [ ] #1432: {Vec,String}::splice – tracking issue
• [ ] #1566: Procedural macros – tracking issue
• [ ] #1576: literal fragment specifier for macro_rules! – tracking issue
• [ ] #1590: lifetime specifier for macro_rules – tracking issue
• [ ] #1845: shared_from_slice – tracking issue
• [ ] #1860: add ManuallyDrop to core – tracking issue
• [x] #1869: eprint! and eprintln! – tracking issue
• [ ] #1884: unstable sort in libcore – tracking issue

1. List accepted, implemented, already-stabilized, undocumented RFCs

This list can be added directly to a newly(-to-be)-created appendix to the Reference.

• [x] Create the appendix (once finished, this list should do just fine, perhaps with some massaging for descriptiveness)

  • [x] #0040: libstd-facade – there is one reference to the facade, in 6.3.13 Compiler Features under a discussion of #[no_std], but no explanation of its meaning. Nor, as far as I can tell, do the relevant sections of the standard library documentation explain this.
  • [x] #0048: Trait reform – some pieces of this are partially documented (the use of Self), but others aren't at all: coherence and orphan rules are covered nowhere. (Currently, the writeup here seems to be the best source on coherence?)
  • [x] #0049: Allow attributes on match arms. – the underlying idea is documented in 6.3 Attributes but the applicability to internal items is never specified.
  • [x] #0131: Some but not all of the flags are documented in 6.3.8 Conditional compilation
  • [x] #0132: Unambiguous function call syntax – not even mentioned
  • [x] #0558: require parentheses for chained comparisons
  • [x] #0560: Integer overflow not unsafe, documented with a reference to the RFC but requires further details
  • [x] #1717: dllimport, one element mentioned but not explained at 6.3.5 FFI attributes
  • [x] #1721: define crt_link
  • [x] #1725: define unaligned_access

2. Write reference material for undocumented, implemented, stabilized RFC features

Each of the features listed above in (1) needs to be documented more formally in the reference.

• [ ] #0040: libstd-facade
• [ ] #0048: (#5) Trait reform, requires documenting coherence and orphan rules (overlaps with Coherence and Orphan rules below in §3)
• [ ] #0049: Allow attributes on match arms: specify applicability to internal items
• [ ] [#0071]: (#13) Allow blocks in constants
• [ ] #0131: Target specification – some but not all of these are in 6.3.8
• [x] #0132: Unambiguous/universal function call syntax – not even mentioned
• [ ] #0179: &mut patterns – symmetry of pattern syntax not documented
• [x] #0558: (#41) require parentheses for chained comparisons – the requirement is not documented in the reference
• [x] #0560: Integer overflow not unsafe, documented with a reference to the RFC but requires further details
• [ ] #1717: dllimport
• [ ] #1721: crt_link
• [ ] #1725: unaligned_access

3. Update out-of-date/incomplete sections of the reference

• [ ] List of language items

  The set of language items is currently considered unstable. A complete list of the built-in language items will be added in the future.

• [ ] Coherence

• [ ] Orphan rules (#5)

• [ ] Lifetime elision

D. Documentation not needed

0. Already documented

1. Retired

2. Removals

3. Parser-specific

4. Process and conventions

5. Non-language features

Note: I've just copied over the original issue as it was—wholesale. Note that some of the links here referencing things as "already documented" will degrade given the new structure of the book.

Thank eddyb and Steve Klabnik for complaining on Twitter for this PR.

Closes #248

The order is now documented. I considered using an example over expression evaluation using println!, but the twitter thread is explicitly using iterators and this is probably the most common reason to care about evaluation order in tuple expressions anyways.

I also cleaned up the page to bring it into style compliance. I did both at the same time, so there's only one noisy commit. Sorry to the reviewer.

I'm not sure what the best reviewing process is here.

cc @cramertj @withoutboats @centril @joshtriplett @pnkfelix @scottmcm @pnkfelix @eddyb (I think that's the lang team, did I miss anybody?)

cc https://github.com/rust-lang-nursery/reference/issues/634 https://github.com/rust-lang/rust/issues/62566

In https://github.com/rust-lang/rust/issues/80657 and https://github.com/rust-lang/rust/pull/80681 it is discussed how to clarify/define what a "logic error" is and what are their consequences. The reference should mention them as well.

We could use other term instead of "unspecified", e.g. "unpredictable"; in case we want to emphasize that the results may not the same between runs, builds, kinds of build, etc. For instance, from the description of integer overflow, it looks like the implementation needs to choose some reasonable behavior (e.g. a panic or wrap around), even if not documented (therefore, "unspecified", in terms of the C and C++ standards). However, logic errors seem to require more freedom: the implementation may not even be able (or want) to predict what may happen, so it cannot "reasonably choose" a particular behavior, even if such behavior is guaranteed to be safe (similar to deadlocks, although in that case the set of possible behavior is known, even if nondeterministic between runs).

As I mentioned in one of the linked discussions, it might be a good idea to define a separate, clear term for this kind of behavior that is considered erroneous and unpredictable, yet safe. So not exactly "unspecified", at least as used in the C and C++ standards -- it is closer to "safe UB" than "unspecified". In other words, in the same spirit as C's "bounded UB" or Ada's "bounded error". Ideally, the term would not overload another common term in other language specs (like UB).

Alternative to #559 incorporating some suggested changes to that PR.

@RalfJung I felt like your pseudocode approached actual code too much, and sorta requires understanding what's going on with Layout in order to follow, so I just took the route of making the padding calculation into an implicit function per other suggestions.

#include<stdio.h>

struct A {
};

int main() {
        struct A a;
        printf("%ld\n", sizeof(a));
}

$ gcc tmp.c
$ ./a.out
0
$ g++ tmp.c
$ ./a.out
1

This makes explicit some de-facto rules that existed at least since Rust 1.0:

• Boxes also have aliasing requirements.
• References must outlive functions they are passed to. (It is not entirely clear that this was intended when the dereferenceable attribute was added, given that the attribute was also added to Box which can definitely be deallocated by functions they are passed to. But when that got fixed in https://github.com/rust-lang/rust/issues/66600, nobody suggested to also remove the attribute from references.)

Irrespective of whether we actually want these rules, they do reflect our current requirements and code not following them risks miscompilations. As such I think we should document them here and consider them the baseline for changes to the aliasing model. It's not great to have a baseline that was never carefully reviewed or designed, but for better or worse that's where we are at.

Also incorporates https://github.com/rust-lang/rust/pull/98017.

Rendered

Cc @rust-lang/lang

This seeks to limit the directives guaranteed to be supported by inline assembly to a subset of those supported by LLVM and GNU AS. The list is chosen as a compromise between utility and implementability, and may be increased in the future.

See discussions here: https://rust-lang.zulipchat.com/#narrow/stream/213817-t-lang/topic/asm!.20and.20backends and https://rust-lang.zulipchat.com/#narrow/stream/216763-project-inline-asm/topic/Defect.20Report.3A.20GNU.20AS.20support

CC: @joshtriplett

Updated reference for stabilization of the #[repr(align(x))] attribute. See tracking issue comments https://github.com/rust-lang/rust/issues/33626#issuecomment-348467804 for discussion.

r? @scottmcm @Gankro @eddyb - Though if you don't want to, just say so and unsubscribe from the thread.

There's no good term for what the compiler calls ADTs - structs, enums, and unions. I cannot think of one either. As such, there's a FIXME in there.

I'm also choosing a very conservative definition of type layout. I'm not sure if it should be expanded or not, or if the valid values and calling convention changes should be a part or not. Although I don't think they should, I don't have any logical arguments either way. Part of the problem is that layout can probably mean multiple things at the same time. E.g. Layout for allocators is just size and alignment.

I initially only wanted to create a version of the GenericArgs non-terminal that doesn’t need 8 cases. On my way there I stumbled across non-terminals that contain the empty word that could easily be changed (much nicer like this IMO), I noticed inconsistencies around parenthesis spacing and fixed some files, found a few typos and mistakes and finally created a bunch of internal links in the tokens.md file.

If any of these changes is controversial I can split it into a different PR.

PR prompted by https://github.com/dtolnay/syn/issues/771

macro_rules! m {
    (#[doc = $tt:tt]) => { stringify!($tt) };
}

fn main() {
    println!(m! {
        ///test
    });
   // output: r"test"
}

Will also open a PR for rustdoc

The reference says:

• Producing an invalid value, even in private fields and locals. "Producing" a value happens any time a value is assigned to or read from a place, passed to a function/primitive operation or returned from a function/primitive operation. The following values are invalid (at their respective type):
  • [...]
  • An integer (i*/u*), floating point value (f*), or raw pointer obtained from uninitialized memory, or uninitialized memory in a str.

and then later:

Note: Uninitialized memory is also implicitly invalid for any type that has a restricted set of valid values. In other words, the only cases in which reading uninitialized memory is permitted are inside unions and in "padding" (the gaps between the fields/elements of a type).

What would be an example of reading uninitialized padding memory? Does this mean that reading uninitialized padding memory is an exception to the above rule (I'm guessing not, but I don't know how to interpret this note otherwise)? Would ptr::read::<u8>(ptr_to_padding) be considered "permitted"? Or does it only mean that ptr::read::<MaybeUninit<u8>>(ptr_to_padding) is "permitted"?

I think this note is unclear and should be reworded. The second sentence also starts with "In other words ...", but these two sentences seem like completely different ideas.

Spawned off of https://github.com/rust-lang/rust/issues/81211#issuecomment-767111563

We need better documentation of the method resolution rules, in terms of how ambiguities are resolved (to either a single method or to a method ambiguity error).

I wrote tests in PR #81294 that tried to enumerate the relevant combinations; see:

• https://github.com/rust-lang/rust/blob/master/src/test/ui/derives/derive-Debug-use-ufcs-struct.rs
• https://github.com/rust-lang/rust/blob/master/src/test/ui/derives/derive-Debug-use-ufcs-tuple.rs

But we still need better docs in the reference

This updates the instruction_set attribute entry to more clearly explain the additional restrictions that the attribute places on inlining. Since Rust performance heavily relies on inlining, it's actually a fairly big deal to document it.

Pinging @pnkfelix as the liaison for the instruction_set attribute during its development.

This explanation is actually slightly looser than the explanation given in the RFC: this explanation allows inlining between no-attribute code without inline asm and other code. So, T-lang should likely approve the update with an FCP or similar process. The intent is that once this is approved as the documentation for how the attribute works then https://github.com/rust-lang/rust/pull/104121 (which updates the MIR inliner to match these rules) will be easier to land.

The 'Dynamically Sized Types' page pretty clearly states that the size of a pointer to a DST is twice the size of a regular pointer:

• Pointer types to DSTs are sized but have twice the size of pointers to sized types

But, the 'Type layout' page gives this much less concrete answer:

• Pointers to unsized types are sized. The size and alignment is guaranteed to be at least equal to the size and alignment of a pointer.

And, in a note, it says the same thing as the DST page, but says that it shouldn't be relied upon:

Note: Though you should not rely on this, all pointers to DSTs are currently twice the size of the size of usize and have the same alignment.

The two pages should be consistent. Assuming that the DST page is correct, the type layout page should also concretely say that pointers to unsized types are twice the size of regular pointers, and the note should be removed.