Merge branch 'master' into fix-72

Author: steveklabnik

src/attributes.md

@@ -184,11 +184,17 @@ macro scope.
   object file that this item's contents will be placed into.
 - `no_mangle` - on any item, do not apply the standard name mangling. Set the
   symbol for this item to its identifier.
-- `doc` - Doc comments such as `/// foo` are equivalent to `#[doc = "foo"]`.
 - `must_use` - on structs and enums, will warn if a value of this type isn't used or
    assigned to a variable. You may also include an optional message by using
    `#[must_use = "message"]` which will be given alongside the warning.
 
+### Documentation
+
+The `doc` attribute is used to document items and fields. [Doc comments]
+are transformed into `doc` attributes.
+
+See [The Rustdoc Book] for reference material on this attribute.
+
 ### Conditional compilation
 
 Sometimes one wants to have different compiler outputs from the same code,
@@ -408,4 +414,6 @@ impl<T: PartialEq> PartialEq for Foo<T> {
 
 You can implement `derive` for your own type through [procedural macros].
 
-[procedural macros]: procedural-macros.html
+[Doc comments]: comments.html#doc-comments
+[The Rustdoc Book]: ../rustdoc/the-doc-attribute.html
+[procedural macros]: procedural-macros.html

src/expressions/method-call-expr.md

@@ -15,23 +15,22 @@ let log_pi = pi.unwrap_or(1.0).log(2.72);
 ```
 
 When resolving method calls on an expression of type `A`, Rust will use the
-following order, only looking at methods that are
-[visible](visibility-and-privacy.html). If the type of `A` is a type parameter
-or `Self` in a trait definitition then steps 2-4 first consider traits from
-bounds on the type paramter, then the traits that are in scope. For other
-types, only the traits that are in scope are considered.
+following order, only looking at methods that are [visible]. If the type of `A`
+is a type parameter or `Self` in a trait definitition then steps 2-4 first
+consider traits from bounds on the type paramter, then the traits that are in
+scope. For other types, only the traits that are in scope are considered.
 
 1. Inherent methods, with receiver of type `A`, `&A`, `&mut A`.
 1. Trait methods with receiver of type `A`.
 1. Trait methods with receiver of type `&A`.
 1. Trait methods with receiver of type `&mut A`.
 1. If it's possible, Rust will then repeat steps 1-5 with
   `<A as std::ops::Deref>::Target`, and insert a dereference operator.
-1. If `A` is now an [array](types.html#array-and-slice-types) type, then
-  repeat steps 1-4 with the corresponding slice type.
+1. If `A` is now an [array] type, then repeat steps 1-4 with the corresponding
+  slice type.
 
-Note: that in steps 1-4 the receiver is used, not the type of `Self` nor the
-type of `A`. For example
+Note: In steps 1-4, the receiver is used, not the type of `Self` nor the
+type of `A`. For example:
 
 ```rust,ignore
 // `Self` is `&A`, receiver is `&A`.
@@ -48,10 +47,21 @@ Another note: this process does not use the mutability or lifetime of the
 receiver, or whether `unsafe` methods can currently be called to resolve
 methods. These constraints instead lead to compiler errors.
 
-If a step is reached where there is more than one possible method (where
-generic methods or traits are considered the same), then it is a compiler
-error. These cases require a [more specific
-syntax.](expressions/call-expr.html#disambiguating-function-calls) for method
+If a step is reached where there is more than one possible method, such as where
+generic methods or traits are considered the same, then it is a compiler
+error. These cases require a [disambiguating function call syntax] for method
 and function invocation.
 
-[IDENTIFIER]: identifiers.html
+> Warning: For [trait objects], if there is an inherent method of the same name
+> as a trait method, it will give a compiler error when trying to call the
+> method in a method call expression. Instead, you can call the method using
+> [disambiguating function call syntax], in which case it calls the trait
+> method, not the inherent method. There is no way to call the inherent method.
+> Just don't define inherent methods on trait objects with the same name a trait
+> method and you'll be fine.
+
+[IDENTIFIER]: identifiers.html
+[visible]: visibility-and-privacy.html
+[array]: types.html#array-and-slice-types
+[trait objects]: types.html#trait-objects
+[disambiguating function call syntax]: expressions/call-expr.html#disambiguating-function-calls

src/expressions/operator-expr.md

@@ -84,13 +84,16 @@ let y = &mut 9;
 assert_eq!(*y, 11);
 ```
 
-## The `?` operator
+## The question mark operator
 
-The `?` ("question mark") operator can be applied to values of the `Result<T,
-E>` type to propagate errors. If applied to `Err(e)` it will return
-`Err(From::from(e))` from the enclosing function or closure. If applied to
-`Ok(x)` it will unwrap the value to return `x`. Unlike other unary operators
-`?` is written in postfix notation. `?` cannot be overloaded.
+The question mark operator (`?`) unwraps valid values or returns errornous
+values, propagating them to the calling function. It is a unary postfix
+operator that can only be applied to the types `Result<T, E>` and `Option<T>`.
+
+When applied to values of the `Result<T, E>` type, it propagates errors. If 
+the value is `Err(e)`, then it will return `Err(From::from(e))` from the
+enclosing function or closure. If applied to `Ok(x)`, then it will unwrap the
+value to evaulate to `x`.
 
 ```rust
 # use std::num::ParseIntError;
@@ -105,6 +108,26 @@ println!("{:?}", res);
 # assert!(res.is_err())
 ```
 
+When applied to values of the `Option<T>` type, it propagates `Nones`. If the
+value is `None`, then it will return `None`. If applied to `Some(x)`, then it
+will unwrap the value to evaluate to `x`.
+
+```rust
+fn try_option_some() -> Option<u8> {
+    let val = Some(1)?;
+    Some(val)
+}
+assert_eq!(try_option_some(), Some(1));
+
+fn try_option_none() -> Option<u8> {
+    let val = None?;
+    Some(val)
+}
+assert_eq!(try_option_none(), None);
+```
+
+`?` cannot be overloaded.
+
 ## Negation operators
 
 These are the last two unary operators. This table summarizes the behavior of

src/glossary.md

@@ -137,5 +137,4 @@ Generic functions and generic structs can use traits to constrain, or bound, the
 [trait objects]: types.html#trait-objects
 [implementations]: items/implementations.html
 [traits]: items/traits.html
-[object safety]: types.html#object-safety
-[trait objects]: types.html#trait-objects
+[object safety]: items/traits.html#object-safety

src/items/enumerations.md

@@ -138,6 +138,6 @@ enum ZeroVariants {}
 [_TupleFields_]: items/structs.html
 [_StructFields_]: items/structs.html
 [enumerated type]: types.html#enumerated-types
-[`mem::discriminant`]: std/mem/fn.discriminant.html
+[`mem::discriminant`]: ../std/mem/fn.discriminant.html
 [numeric cast]: expressions/operator-expr.html#semantics
 [`repr` attribute]: attributes.html#ffi-attributes

src/items/static-items.md

@@ -114,7 +114,7 @@ following are true:
 * Interior mutability is required.
 
 [constant]: items/constant-items.html
-[interior mutable]: interior_mutability.html
+[interior mutable]: interior-mutability.html
 [IDENTIFIER]: identifiers.html
 [_Type_]: types.html
 [_Expression_]: expressions.html

src/items/traits.md

@@ -215,26 +215,18 @@ fn draw_figure<U: Shape>(surface: Surface, Figure(sh1, sh2): Figure<U>) {
 }
 ```
 
-## Trait objects
+## Object Safety
 
-Traits also define a [trait object] with the same name as the trait. Values of
-this type are created by coercing from a pointer of some specific type to a
-pointer of trait type. For example, `&T` could be coerced to `&Shape` if `T:
-Shape` holds (and similarly for `Box<T>`). This coercion can either be implicit
-or [explicit]. Here is an example of an explicit coercion:
+Object safe traits can be the base trait of a [trait object]. A trait is
+*object safe* if it has the following qualities (defined in [RFC 255]):
 
-```rust
-trait Shape { }
-impl Shape for i32 { }
-let mycircle = 0i32;
-let myshape: Box<Shape> = Box::new(mycircle) as Box<Shape>;
-```
-
-The resulting value is a box containing the value that was cast, along with
-information that identifies the methods of the implementation that was used.
-Values with a trait type can have [methods called] on them, for any method in
-the trait, and can be used to instantiate type parameters that are bounded by
-the trait.
+* It must not require `Self: Sized`
+* All associated functions must either have a `where Self: Sized` bound or
+    * Not have any type parameters (although lifetime parameters are allowed)
+    * Must be a method: its first parameter must be called self, with type
+      `Self`, `&Self`, `&mut Self`, `Box<Self>`.
+    * `Self` may only be used in the type of the receiver.
+* It must not have any associated constants.
 
 ## Supertraits
 
@@ -302,6 +294,11 @@ let mycircle = Box::new(mycircle) as Box<Circle>;
 let nonsense = mycircle.radius() * mycircle.area();
 ```
 
+[`Send`]: ../std/marker/trait.Send.html
+[`Send`]: ../std/marker/trait.Sync.html
+[`UnwindSafe`]: ../std/panic/trait.UnwindSafe.html
+[`RefUnwindSafe`]: ../std/panic/trait.RefUnwindSafe.html
 [trait object]: types.html#trait-objects
 [explicit]: expressions/operator-expr.html#type-cast-expressions
-[methods called]: expressions/method-call-expr.html
+[methods called]: expressions/method-call-expr.html
+[RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md

src/paths.md

@@ -1,9 +1,9 @@
 # Paths
 
-A _path_ is a sequence of one or more path components _logically_ separated by
-a namespace qualifier (`::`). If a path consists of only one component, it may
-refer to either an [item] or a [variable] in a local control
-scope. If a path has multiple components, it refers to an item.
+A *path* is a sequence of one or more path components _logically_ separated by
+a namespace qualifier (`::`). If a path consists of only one component, it
+refers to either an [item] or a [variable] in a local control
+scope. If a path has multiple components, it always refers to an item.
 
 Two examples of simple paths consisting of only identifier components:
 

src/special-types-and-traits.md

@@ -127,19 +127,19 @@ compiler, not by [implementation items].
 [`Sync`]: ../std/marker/trait.Sync.html
 
 [Arrays]: types.html#array-and-slice-types
-[call expressions]: expressoins/call-expr.html
+[call expressions]: expressions/call-expr.html
 [deref coercions]: type-coercions.html#coercion-types
 [dereference operator]: expressions/operator-expr.html#the-dereference-operator
 [destructor]: destructors.html
 [drop check]: ../nomicon/dropck.html
 [dynamically sized type]: dynamically-sized-types.html
 [Function pointers]: types.html#function-pointer-types
 [function item types]: types.html#function-item-types
-[implementation items]: items.html/implementations.html
+[implementation items]: items/implementations.html
 [indexing expressions]: expressions/array-expr.html#array-and-slice-indexing-expressions
-[interior mutability]: iterior-mutability.html
+[interior mutability]: interior-mutability.html
 [Numeric types]: types.html#numeric-types
-[Methods]: items.html#associated-functions-and-methods
+[Methods]: items/traits.html#associated-functions-and-methods
 [method resolution]: expressions/method-call-expr.html
 [operators]: expressions/operator-expr.html
 [orphan rules]: items/implementations.html#trait-implementation-coherence

src/statements.md

@@ -1,33 +1,48 @@
 # Statements
 
-A _statement_ is a component of a block, which is in turn a component of an
-outer [expression](expressions.html) or [function](items/functions.html).
+A *statement* is a component of a [block], which is in turn a component of an
+outer [expression] or [function].
 
 Rust has two kinds of statement: [declaration
 statements](#declaration-statements) and [expression
 statements](#expression-statements).
 
 ## Declaration statements
 
-A _declaration statement_ is one that introduces one or more *names* into the
+A *declaration statement* is one that introduces one or more *names* into the
 enclosing statement block. The declared names may denote new variables or new
-items.
+[items][item].
+
+The two kinds of declaration statements are item declarations and `let`
+statements.
 
 ### Item declarations
 
-An _item declaration statement_ has a syntactic form identical to an
-[item](items.html) declaration within a module. Declaring an item — a
-function, enumeration, struct, type, static, trait, implementation or module
-— locally within a statement block is simply a way of restricting its
-scope to a narrow region containing all of its uses; it is otherwise identical
-in meaning to declaring the item outside the statement block.
+An *item declaration statement* has a syntactic form identical to an
+[item declaration][item] within a [module]. Declaring an item within a statement
+block restricts its scope to the block containing the statement. The item is not
+given a [canonical path] nor are any sub-items it may declare. The exception to
+this is that associated items defined by [implementations] are still accessible
+in outer scopes as long as the item and, if applicable, trait are accessible.
+It is otherwise identical in meaning to declaring the item inside a module.
+
+There is no implicit capture of the containing function's generic parameters,
+parameters, and local variables. For example, `inner` may not access
+`outer_var`.
+
+```rust
+fn outer() {
+  let outer_var = true;
 
-> **Note**: there is no implicit capture of the function's dynamic environment when
-> declaring a function-local item.
+  fn inner() { /* outer_var is not in scope here */ }
+
+  inner();
+}
+```
 
 ### `let` statements
 
-A _`let` statement_ introduces a new set of variables, given by a pattern. The
+A *`let` statement* introduces a new set of variables, given by a pattern. The
 pattern may be followed by a type annotation, and/or an initializer expression.
 When no type annotation is given, the compiler will infer the type, or signal
 an error if insufficient type information is available for definite inference.
@@ -36,13 +51,15 @@ declaration until the end of the enclosing block scope.
 
 ## Expression statements
 
-An _expression statement_ is one that evaluates an
-[expression](expressions.html) and ignores its result. As a rule, an expression
-statement's purpose is to trigger the effects of evaluating its expression.
-An expression that consists of only a [block
-expression](expressions/block-expr.html) or control flow expression,
-that doesn't end a block and evaluates to `()` can also be used as an
-expression statement by omitting the trailing semicolon.
+An *expression statement* is one that evaluates an [expression] and ignores its
+result. As a rule, an expression statement's purpose is to trigger the effects
+of evaluating its expression.
+
+An expression that consists of only a [block expression][block] or control flow
+expression, if used in a context where a statement is permitted, can omit the
+trailing semicolon. This can cause an ambiguity between it being parsed as a
+standalone statement and as a part of another expression; in this case, it is
+parsed as a statement.
 
 ```rust
 # let mut v = vec![1, 2, 3];
@@ -54,3 +71,28 @@ if v.is_empty() {
 }                 // Semicolon can be omitted.
 [1];              // Separate expression statement, not an indexing expression.
 ```
+
+When the trailing semicolon is omitted, the result must be type `()`.
+
+```rust
+// bad: the block's type is i32, not ()
+// Error: expected `()` because of default return type
+// if true {
+//   1
+// }
+
+// good: the block's type is i32
+if true {
+  1
+} else {
+  2
+};
+```
+
+[block]: expressions/block-expr.html
+[expression]: expressions.html
+[function]: items/functions.html
+[item]: items.html
+[module]: items/modules.html
+[canonical path]: paths.html#canonical-paths
+[implementations]: items/implementations.html

src/tokens.md

@@ -318,7 +318,7 @@ literal_. The grammar for recognizing the two kinds of literals is mixed.
 >  
 > INTEGER_SUFFIX :  
 >       `u8` | `u16` | `u32` | `u64` | `usize`  
->    | `i8` | `u16` | `i32` | `i64` | `usize`
+>    | `i8` | `i16` | `i32` | `i64` | `isize`
 
 <!-- FIXME: separate the DECIMAL_LITERAL with no prefix or suffix (used on tuple indexing and float_literal -->
 <!-- FIXME: u128 and i128 -->

src/type-layout.md

@@ -281,7 +281,7 @@ padding bytes and forcing the alignment of the type to `1`.
 [`size_of`]: ../std/mem/fn.size_of.html
 [`Sized`]: ../std/marker/trait.Sized.html
 [dynamically sized types]: dynamically-sized-types.html
-[C-like enumerations]: items/enumerations.html#c-like-enumerations
-[zero-variant enumerations]: items/enumerations.html#zero-variant-enumerations
+[C-like enumerations]:  items/enumerations.html#custom-discriminant-values-for-field-less-enumerations
+[zero-variant enumerations]: items/enumerations.html#zero-variant-enums
 [undefined behavior]: behavior-considered-undefined.html
 [27060]: https://github.com/rust-lang/rust/issues/27060