Audit reference manual before 1.0

[brson]

Shortly before 1.0 we should give some attention to the manual and make sure it's not too inaccurate nor incomplete.

---

Let's crowdsource this edit! Please check one of these sections, and leave a comment below if you've verified that it's accurate or have sent a PR fixing part:

• 1 Introduction
• 2 Notation
• 2.1 Unicode productions
• 2.2 String table productions
• 3 Lexical structure
• 3.1 Input format
• 3.2 Special Unicode Productions
• 3.2.1 Identifiers
• 3.2.2 Delimiter-restricted productions
• 3.3 Comments
• 3.4 Whitespace
• 3.5 Tokens
• 3.5.1 Keywords
• 3.5.2 Literals
• 3.5.2.1 Examples
• 3.5.2.1.1 Characters and strings
• 3.5.2.1.2 Byte escapes
• 3.5.2.1.3 Unicode escapes
• 3.5.2.1.4 Numbers
• 3.5.2.1.5 Suffixes
• 3.5.2.2 Character and string literals
• 3.5.2.2.1 Character literals
• 3.5.2.2.2 String literals
• 3.5.2.2.3 Character escapes
• 3.5.2.2.4 Raw string literals
• 3.5.2.3 Byte and byte string literals
• 3.5.2.3.1 Byte literals
• 3.5.2.3.2 Byte string literals
• 3.5.2.3.3 Raw byte string literals
• 3.5.2.4 Number literals
• 3.5.2.4.1 Integer literals
• 3.5.2.4.2 Floating-point literals
• 3.5.2.5 Boolean literals
• 3.5.3 Symbols
• 3.6 Paths
• 4 Syntax extensions
• 4.1 Macros
• 4.1.1 Macro By Example
• 4.1.2 Parsing limitations
• 5 Crates and source files
• 6 Items and attributes
• 6.1 Items
• 6.1.1 Type Parameters
• 6.1.2 Modules
• 6.1.2.0.1 Extern crate declarations
• 6.1.2.0.2 Use declarations
• 6.1.3 Functions
• 6.1.3.1 Generic functions
• 6.1.3.2 Unsafety
• 6.1.3.2.1 Unsafe functions
• 6.1.3.2.2 Unsafe blocks
• 6.1.3.2.3 Behavior considered undefined
• 6.1.3.2.4 Behaviour not considered unsafe
• 6.1.3.3 Diverging functions
• 6.1.3.4 Extern functions
• 6.1.4 Type aliases
• 6.1.5 Structures
• 6.1.6 Enumerations
• 6.1.7 Constant items
• 6.1.8 Static items
• 6.1.8.1 Mutable statics
• 6.1.9 Traits
• 6.1.10 Implementations
• 6.1.11 External blocks
• 6.2 Visibility and Privacy
• 6.2.1 Re-exporting and Visibility
• 6.3 Attributes
• 6.3.1 Crate-only attributes
• 6.3.2 Module-only attributes
• 6.3.3 Function-only attributes
• 6.3.4 Static-only attributes
• 6.3.5 FFI attributes
• 6.3.6 Macro-related attributes
• 6.3.7 Miscellaneous attributes
• 6.3.8 Conditional compilation
• 6.3.9 Lint check attributes
• 6.3.10 Language items
• 6.3.11 Inline attributes
• 6.3.12 derive
• 6.3.13 Compiler Features
• 7 Statements and expressions
• 7.1 Statements
• 7.1.1 Declaration statements
• 7.1.1.1 Item declarations
• 7.1.1.2 Variable declarations
• 7.1.2 Expression statements
• 7.2 Expressions
• 7.2.0.1 Lvalues, rvalues and temporaries
• 7.2.0.2 Moved and copied types
• 7.2.1 Literal expressions
• 7.2.2 Path expressions
• 7.2.3 Tuple expressions
• 7.2.4 Unit expressions
• 7.2.5 Structure expressions
• 7.2.6 Block expressions
• 7.2.7 Method-call expressions
• 7.2.8 Field expressions
• 7.2.9 Array expressions
• 7.2.10 Index expressions
• 7.2.11 Unary operator expressions
• 7.2.12 Binary operator expressions
• 7.2.12.1 Arithmetic operators
• 7.2.12.2 Bitwise operators
• 7.2.12.3 Lazy boolean operators
• 7.2.12.4 Comparison operators
• 7.2.12.5 Type cast expressions
• 7.2.12.6 Assignment expressions
• 7.2.12.7 Compound assignment expressions
• 7.2.12.8 Operator precedence
• 7.2.13 Grouped expressions
• 7.2.14 Call expressions
• 7.2.15 Lambda expressions
• 7.2.16 While loops
• 7.2.17 Infinite loops
• 7.2.18 Break expressions
• 7.2.19 Continue expressions
• 7.2.20 For expressions
• 7.2.21 If expressions
• 7.2.22 Match expressions
• 7.2.23 If let expressions
• 7.2.24 While let loops
• 7.2.25 Return expressions
• 8 Type system
• 8.1 Types
• 8.1.1 Primitive types
• 8.1.1.1 Machine types
• 8.1.1.2 Machine-dependent integer types
• 8.1.2 Textual types
• 8.1.3 Tuple types
• 8.1.4 Array, and Slice types
• 8.1.5 Structure types
• 8.1.6 Enumerated types
• 8.1.7 Recursive types
• 8.1.8 Pointer types
• 8.1.9 Function types
• 8.1.10 Closure types
• 8.1.11 Object types
• 8.1.12 Type parameters
• 8.1.13 Self types
• 9 Special traits
• 9.1 The Copy trait
• 9.2 The Sized trait
• 9.3 The Drop trait
• 10 Memory model
• 10.0.1 Memory allocation and lifetime
• 10.0.2 Memory ownership
• 10.0.3 Variables
• 11 Linkage
• 12 Appendix: Rationales and design tradeoffs
• 13 Appendix: Influences

[steveklabnik]

Very yes.

[aturon]

I'm going to assign this to myself, as we decided at the work week, but I will be working with/delegating to others on actually carrying this out.

[aturon]

Re-nominating. Should this be on the beta milestone?

[pnkfelix]

leaving on the 1.0 milestone; this is considered polish, after we've finished all the backwards incompat stuff.

[steveklabnik]

#24721

[rkruppe]

Audited section 5, Crates and source files. Filed PR #24727 to fix it.

[bluss]

I'm reading 8.1, the types chapter. PR #24744

I didn't really cover 8.1.13 Self types, someone should look at that again.

[joliv]

Audited 7.2.4 (Unit expressions) and filed #24738

EDIT: Let me rescind that—I'm told that, as the unit type is no longer viewed as being separate from the tuple, the reference is going to need a bit more of an overhaul than what I've done in the PR, including possibly taking out the section I've edited.

[mbrubeck]

Audited 3.3 (Comments). Filed #24740 for a small clarification. Aside from that it looks good, although I think the EBNF is a little sketchy. (character is not defined anywhere, for example, and I think perhaps it needs the restriction that it can't include */?)

[mbrubeck]

Audited 3.5.1 (Keywords). Filed #24742 to add two missing keywords.

[joliv]

6.1.4 (Type Aliases) looks good to me.

[tynopex]

#24753 - describe Range expressions

[jackm321]

If the unit type is no longer present, will unit-like structs be renamed to something else?

[steveklabnik]

Thanks @badboy !

I believe you are right, would you mind sending a PR?

[badboy]

Will do

[johannhof]

@steveklabnik read through some of chapter 7, wouldn't want to greenlight it yet but found what I think is a small issue and made a pr: #25286

[bluss]

Audited as ok:

• 3.3 Comments
• 3.4 Whitespace
• 3.5
• 3.5.1 Keywords
• 3.5.2
• 3.5.2.2 Character and string literals
• 3.5.2.2.1
• 3.5.1.3.2 Byte string literals
• 3.5.1.3.3 Raw byte string literals
• 3.5.1.4 Number literals
• 3.5.1.4.1 Integer literals
• 3.5.1.4.2 Floating-point literals

Pending PR #25290 to fix:

• 6 Items and attributes
• 6.1 Items
• 6.1.1 Type Parameters
• 6.1.2.0.1 Extern crate declarations
• 6.1.2.0.2 Use declarations

[dhardy]

Since #24863 was merged, all of 3.5.2 can be marked as done (sorry bluss for letting you repeat work)

[bluss]

Well since I read the fixed version it was easy :)

[nham]

I read 6.1.9 (and part of 8.1.11) and submitted a PR: #25308

[steveklabnik]

I'm considering this closed, as both @nikomatsakis and I did a full read-over, and the community chipped in a ton as well.

Future improvements to the reference are always welcome, of course.