Add more content to impl-trait.md

src/types/impl-trait.md

@@ -5,33 +5,120 @@
 >
 > _ImplTraitTypeOneBound_ : `impl` [_TraitBound_]
 
-## Anonymous type parameters
+> **Edition differences**: `impl Trait` is new in the 2018 edition.
+
+`impl Trait` provides ways to specify unnamed but concrete types that
+implement a specific trait.
+It can appear in two sorts of places: argument position (where it can act as an anonymous type parameter to functions), and return position (where it can act as an abstract return type).
 
-> Note: This section is a placeholder for more comprehensive reference
-> material.
+```rust
+trait Trait {}
+# impl Trait for () {}
+
+// argument position: anonymous type parameter
+fn foo(arg: impl Trait) {
+}
+
+// return position: abstract return type
+fn bar() -> impl Trait {
+}
+```
+## Anonymous type parameters
 
 > Note: This is often called "impl Trait in argument position".
 
-Functions can declare an argument to be an anonymous type parameter where the
-callee must provide a type that has the bounds declared by the anonymous type
-parameter and the function can only use the methods available by the trait
-bounds of the anonymous type parameter.
+Functions can use `impl` followed by a set of trait bounds to declare an argument as having an anonymous type.
+The caller must provide a type that satisfies the bounds declared by the anonymous type parameter, and the function can only use the methods available through the trait bounds of the anonymous type parameter.
 
-They are written as `impl` followed by a set of trait bounds.
+For example, these two forms are almost equivalent:
 
-## Abstract return types
+```rust,ignore
+trait Trait {}
+
+// generic type parameter
+fn foo<T: Trait>(arg: T) {
+}
 
-> Note: This section is a placeholder for more comprehensive reference
-> material.
+// impl Trait in argument position
+fn foo(arg: impl Trait) {
+}
+```
+
+That is, `impl Trait` in argument position is syntactic sugar for a generic type parameter like `<T: Trait>`, except that the type is anonymous and doesn't appear in the [_GenericParams_] list.
+
+> **Note:**
+> For function arguments, generic type parameters and `impl Trait` are not exactly equivalent.
+> With a generic parameter such as `<T: Trait>`, the caller has the option to explicitly specify the generic argument for `T` at the call site using [_GenericArgs_], for example, `foo::<usize>(1)`.
+> If `impl Trait` is the type of a function argument, then the caller can't ever specify the type of that argument by using a generic argument.
+>
+> Therefore, changing the function signature from either one to the other can constitute a breaking change for the callers of a function.
+
+## Abstract return types
 
 > Note: This is often called "impl Trait in return position".
 
-Functions, except for associated trait functions, can return an abstract
-return type. These  types stand in for another concrete type where the
-use-site may only use the trait methods declared by the trait bounds of the
-type.
+Functions can use `impl Trait` to return an abstract return type.
+These types stand in for another concrete type where the caller may only use the methods declared by the specified `Trait`.
+Each possible return value from the function must resolve to the same concrete type.
+
+`impl Trait` in return position allows a function to return an unboxed abstract type.
+This is particularly useful with [closures] and iterators.
+For example, closures have a unique, un-writable type.
+Previously, the only way to return a closure from a function was to use a [trait object]:
+
+```rust
+fn returns_closure() -> Box<dyn Fn(i32) -> i32> {
+    Box::new(|x| x + 1)
+}
+```
+
+This could incur performance penalties from heap allocation and dynamic dispatch.
+It wasn't possible to fully specify the type of the closure, only to use the `Fn` trait.
+That means that the trait object is necessary.
+However, with `impl Trait`, it is possible to write this more simply:
+
+```rust
+fn returns_closure() -> impl Fn(i32) -> i32 {
+    |x| x + 1
+}
+```
+
+which also avoids the drawbacks of using a boxed trait object.
+
+Similarly, the concrete types of iterators could become very complex, incorporating the types of all previous iterators in a chain.
+Returning `impl Iterator` means that a function only exposes the `Iterator` trait as a bound on its return type, instead of explicitly specifying all of the other iterator types involved.
+
+### Differences between generics and `impl Trait` in return position
+
+In argument position, `impl Trait` is very similar in semantics to a generic type parameter.
+However, there are significant differences between the two in return position.
+With `impl Trait`, unlike with a generic type parameter, the function chooses the return type, and the caller cannot choose the return type.
+
+The function:
+
+```rust,ignore
+fn foo<T: Trait>() -> T {
+```
+
+allows the caller to determine the return type, `T`, and the function returns that type.
+
+The function:
+
+```rust,ignore
+fn foo() -> impl Trait {
+```
+
+doesn't allow the caller to determine the return type.
+Instead, the function chooses the return type, but only promises that it will implement `Trait`.
+
+## Limitations
 
-They are written as `impl` followed by a set of trait bounds.
+`impl Trait` can only appear as the argument or return type of a free or inherent function.
+It cannot appear inside implementations of traits, nor can it be the type of a let binding or appear inside a type alias.
 
+[closures]: closure.md
+[_GenericArgs_]: ../paths.md#paths-in-expressions
+[_GenericParams_]: ../items/generics.md
 [_TraitBound_]: ../trait-bounds.md
+[trait object]: trait-object.md
 [_TypeParamBounds_]: ../trait-bounds.md