Moar trait object verbiage.

1. While it's "obvious", it should be stated that trait objects actually
   implement the traits they are for.

2. Added lifetime bounds to the syntactical description and aliasing
   rules of trait objects. I'm not sure if the aliasing part is correct.

3. Added a big fat warning to the method call expression about trait
   objects having an inherent impl define a method with the same name
   as one of the methods the trait object has from the trait. I
   think that trait objects following different rules than other types
   should be changed.

Author: Havvy

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/types.md

@@ -403,13 +403,19 @@ A *trait object* is an opaque value of another type that implements a set of
 traits. The set of traits is made up of an [object safe] *base trait* plus any
 number of [auto traits].
 
+Trait objects implement the base trait, its auto traits, and any super traits
+of the base trait.
+
 Trait objects are written as the path to the base trait followed by the list
-of auto traits all separated by `+`. For example, given a trait `Trait`, the
-following are all trait objects: `Trait`, `Trait + Send`, `Trait + Send + Sync`.
+of auto traits followed optionally by a lifetime bound all separated by `+`. For
+example, given a trait `Trait`, the following are all trait objects: `Trait`,
+`Trait + Send`, `Trait + Send + Sync`, `Trait + 'static`,
+`Trait + Send + 'static`.
 
 Two trait object types alias each other if the base traits alias each other and
-if the sets of auto traits are the same. For example,
-`Trait + Send + UnwindSafe` is the same as `Trait + Unwindsafe + Send`.
+if the sets of auto traits are the same and the lifetime bounds are the same.
+For example, `Trait + Send + UnwindSafe` is the same as
+`Trait + Unwindsafe + Send`.
 
 > Warning: With two trait object types, even when the complete set of traits is
 > the same, if the base traits differ, the type is different. For example,