Merge pull request rust-lang#172 from Havvy/trait-objects

Small changes around trait objects

Author: QuietMisdreavus

src/glossary.md

@@ -70,6 +70,11 @@ unsafe Rust can create such a memory without initializing it.
 Types that can be referred to by a path directly. Specifically [enums],
 [structs], [unions], and [trait objects].
 
+### Object Safe Traits
+
+[Traits] that can be used as [trait objects]. Only traits that follow specifc
+[rules][object safety] are object safe. 
+
 ### Prelude
 
 Prelude, or The Rust Prelude, is a small collection of items - mostly traits - that are
@@ -131,4 +136,6 @@ Generic functions and generic structs can use traits to constrain, or bound, the
 [unions]: items/unions.html
 [trait objects]: types.html#trait-objects
 [implementations]: items/implementations.html
-[traits]: items/traits.html
+[traits]: items/traits.html
+[object safety]: types.html#object-safety
+[trait objects]: types.html#trait-objects

src/items/traits.md

@@ -223,9 +223,6 @@ 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:
 
-[trait object]: types.html#trait-objects
-[explicit]: expressions/operator-expr.html#type-cast-expressions
-
 ```rust
 trait Shape { }
 impl Shape for i32 { }
@@ -239,12 +236,10 @@ 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.
 
-[methods called]: expressions/method-call-expr.html
-
 ## Supertraits
 
 Trait bounds on `Self` are considered "supertraits". These are required to be
-acyclic.  Supertraits are somewhat different from other constraints in that
+acyclic. Supertraits are somewhat different from other constraints in that
 they affect what methods are available in the vtable when the trait is used as
 a [trait object]. Consider the following example:
 
@@ -306,3 +301,7 @@ Likewise, supertrait methods may also be called on trait objects.
 let mycircle = Box::new(mycircle) as Box<Circle>;
 let nonsense = mycircle.radius() * mycircle.area();
 ```
+
+[trait object]: types.html#trait-objects
+[explicit]: expressions/operator-expr.html#type-cast-expressions
+[methods called]: expressions/method-call-expr.html

src/types.md

@@ -405,10 +405,8 @@ x = bo(5,7);
 
 In Rust, trait names also refer to [dynamically sized types] called _trait
 objects_. Like all <abbr title="dynamically sized types">DSTs</abbr>, trait
-objects are used behind some kind of pointer: `&SomeTrait` or `Box<SomeTrait>`.
-Each instance of a pointer to a trait object includes:
-
-[dynamically sized types]: dynamically-sized-types.html
+objects are used behind some type of pointer; for example `&SomeTrait` or
+`Box<SomeTrait>`. Each instance of a pointer to a trait object includes:
 
  - a pointer to an instance of a type `T` that implements `SomeTrait`
  - a _virtual method table_, often just called a _vtable_, which contains, for
@@ -421,9 +419,8 @@ function pointer is loaded from the trait object vtable and invoked indirectly.
 The actual implementation for each vtable entry can vary on an object-by-object
 basis.
 
-Note that trait object types only exist for _object-safe_ traits ([RFC 255]):
-
-[RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md
+Note that trait object types only exist for
+<span id="object-safety">*object-safe*</span> traits ([RFC 255]):
 
 * It must not require `Self: Sized`
 * All associated functions must either have a `where Self: Sized` bound or
@@ -467,9 +464,6 @@ need to be expressed as part of the trait object. The assumed lifetime of
 references held by a trait object is called its _default object lifetime bound_.
 These were defined in [RFC 599] and amended in [RFC 1156].
 
-[RFC 599]: https://github.com/rust-lang/rfcs/blob/master/text/0599-default-object-bound.md
-[RFC 1156]: https://github.com/rust-lang/rfcs/blob/master/text/1156-adjust-default-object-bounds.md
-
 For traits that themselves have no lifetime parameters:
 * If there is a unique bound from the containing type then that is the default
 * If there is more than one bound from the containing type then an explicit bound must
@@ -580,3 +574,8 @@ impl Printable for String {
 ```
 
 The notation `&self` is a shorthand for `self: &Self`.
+
+[dynamically sized types]: dynamically-sized-types.html
+[RFC 599]: https://github.com/rust-lang/rfcs/blob/master/text/0599-default-object-bound.md
+[RFC 1156]: https://github.com/rust-lang/rfcs/blob/master/text/1156-adjust-default-object-bounds.md
+[RFC 255]: https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md