Document all features in the reference #38643

Last updated February 10, 2017, now processing a fork of @Eh2406's wonderful gist.

Tracking issue for RFC #1636. 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.)

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: 75/291

RFCs unreviewed

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

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

• #1131: Add an expect intrinsic
• #1624: loop_break_value
• #1665: Windows subsystem support

0.2 Track accepted, not-yet-implemented, undocumented RFCs

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

• #0066: Better temporary lifetimes

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

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

• Create the appendix

  • #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.
  • #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?)
  • #0049: Allow attributes on match arms. – the underlying idea is documented in 6.3 Attributes but the applicability to internal items is never specified.
  • #0558: require parentheses for chained comparisons
  • #0560: Integer overflow not unsafe, documented with a reference to the RFC but requires further details
  • #1717: dllimport, one element mentioned but not explained at 6.3.5 FFI attributes
  • #1721: define crt_link
  • #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: 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
• #0558: require parentheses for chained comparisons -- the requirement is not documented in the reference
• #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

• Lifetime elision

Documentation not needed

Already documented

• #0001: Private fields by default, in 6.2 Visibility and Privacy
• #0003: Rearchitect the attribute-usage lint, in 6.3 Attributes
• #0016: attributes on statements and blocks, in 6.3 Attributes
• #0034: well-formed trait bounds, in 6.1.9 Traits
• #0042: regexp crate – library documented here; could also be treated as Retired since it's currently still part of the nursery and not part of std.
• #0050: adds debug_assert! and assert!; documented at std::debug_assert and std::assert.
• #0060: rename StrBuf to String; documented at std::string::String and collections::string::String.
• #0068: change *T to *const T; documented at 8.1.8 Pointer types
• #0069: add ASCII byte literals and ASCII byte string literals to the language; documented at 3.5.1.3 Byte and byte string literals
• #0109; documented at 5 Crates and source files and used as part of an example in the current Rust book (Custom Allocators)
• #0123: rename Share trait; documented at std::marker::Sync
• #0135: where classes; documented at 6.1.3.1 Generic functions and discussed thoroughly in both the current and upcoming versions of the book.
• #0214: while letloops; documented at 7.2.24 while let loops.
• #0164: Feature gate pattern-matching on slices; documented as feature-flagged and unstable at 6.3.13 Compiler features.
• #0390: Define variants in a sub-namespace of their enum; clear from all examples at 6.1.6 Enumerations and in the book, and explicit in the discussion of paths in 6.1 Items.
• #0403: Cargo build command—not, strictly speaking, a language detail; and documented in the book and at doc.crates.io.
• #0446: ES6-style unicode string escaping, documented at 3.5.1.1.3 Unicode escapes.
• #0450: Un-feature-gate tuple_indexing, if_let, and while_let, documented at 8.1.3 Tuple types, 7.2.23 if let expressions, 7.2.24 while let loops.
• #0520: Array syntax [T; N] and [x; N], documented in 8.1.4 Array and Slice types.
• #0544: Rename int to usize/isize, documented in 8.1.1.2 Machine-dependent integer types
• #0563: Remove ndebug config variable -- replaced with debug_assertions, documented at 6.3.8 Conditional Compilation
• #1054: change str::words() to str::split_whitespace(), documented in std
• #1057: add the Sync bound to io::Error, documented at std::io::Error
• #1058: replace slice.tail(), slice.init() with slice.split_first(), slice.split_last(), documented at slice
• #1066: change std::mem::forget not to be unsafe (though it is not safe), behavior is carefully and fully documented at std::mem::forget
• #1102: replace SliceConcatExt::connect with SliceConcatExt::join, documented in std
• #1119: add result::Result::expect() method, documented in std
• #1123: add str::split_at() method, documented in std
• #1618: relax format_args! type restrictions, documented in std
• #1620: regex-1.0, documented in-tree at the crate docs (this is a library issue, not a reference issue)
• #1640: duration_checked, documented in std

Retired

These items were accepted, but never implemented and not currently planned to be implemented and therefore not in need of documentation.

• #0008: New intrinsics
• #0112: Remove cross borrowing coercion. Replaced by the removal in #0139.
• #0115: do not fall back to int if cannot infer integer; replaced with #0212.
• #0155: only allow "anonymous impl" (impl Foo) in the same module as the data type is defined (struct Foo or mod Foo). Replaced by #0735.

Removals

Some items constitute not additions to be documented but things removed from the language. These do not require documentation (for obvious reasons!).

• #0026: Remove the priv keyword
• #0059: Remove ~ in favor of box and Box
• #0063: Tighten restrictions on mod
• #0093: Remove localization from format!
• #0139: Remove cross borrowing entirely.
• #0230: Remove runtime
• #0256: Remove refcounting Gc<T> from stdlib
• #0341: Remove "virtual struct"/struct inheritance feature
• #0379: Remove reflection (libdebug, Poly trait, and an earlier version of :?, since repurposed)
• #0385: Module system cleanup and simplification (current module rules are documented; these changes removed restrictions)
• #0533: Remove support for moving individual elements into uninitialized arrays or out of fixed-sized arrays
• #1096: Remove static_assert

Process and conventions

• #0199: Conventions for ownership variants (naming conventions, mostly internal interest)
• #0235: Conventions for collections and iterables (and a few other things)
• #0236: Conventions for error handling
• #0507: Release channels
• #0531: RFC scope and Rust "distribution" definition
• #1068: Scaling Rust's governance
• #1105: API evolution and versioning guidelines
• #1122: Rust language SemVer definitions
• #1589: Define the rustc bugfix best practices
• #1607: RFC process for formatting style and Rustfmt defaults (results will be captured in a non-reference document)
• #1636: Document All Features (process) (this PR!)
• #1643: Dedicated strike team to resolve unsafe code guidelines (results should be captured in the Reference, but this issue itself not so much)
• #1644: Default and expanded errors for rustc
• #1683: Create a docs subteam
• #1728: North Star (process)