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

[hanna-kruppe]

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?

[badboy]

I read:

4 Syntax extensions
4.1 Macros
4.1.1 Macro By Example
4.1.2 Parsing limitations

…, so ( $( $i:ident ),* ; $( $j:ident ),* ) => ( $( ($i,$j) ),* ) is valid if given the argument (a,b,c ; d,e,f), but not (a,b,c ; d,e). The repetition walks through the choices at that layer in lockstep, so the former input transcribes to ( (a,d), (b,e), (c,f) ).

Directly used as this in a macro fails, because it's not actually ( (a,d), (b,e), (c,f) ), but missing the outer parentheses (http://is.gd/D09NUj).
Adding another pair works: http://is.gd/1RO4Mq
If I'm right a pair of parentheses (or curly braces) are used to seperate the block of code, but this is not mentioned in the text at all. Should it be thus added and the example adjused?

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