Further improve docs for FnDef and FnPtr

src/librustc/ty/sty.rs

@@ -126,26 +126,24 @@ pub enum TyKind<'tcx> {
     Ref(Region<'tcx>, Ty<'tcx>, hir::Mutability),
 
     /// The anonymous type of a function declaration/definition. Each
-    /// function has a unique type.
+    /// function has a unique type, which is output (for a function
+    /// named `foo` returning an `i32`) as `fn() -> i32 {foo}`.
     ///
-    /// For example the type of `a` here:
+    /// For example the type of `bar` here:
     ///
     /// ```rust
     /// fn foo() -> i32 { 1 }
-    ///
-    /// fn hello() {
-    ///     let a = foo;
-    /// }
+    /// let bar = foo; // bar: fn() -> i32 {foo}
     /// ```
     FnDef(DefId, &'tcx Substs<'tcx>),
 
     /// A pointer to a function.  Written as `fn() -> i32`.
     ///
-    /// For example the type of `a` here:
+    /// For example the type of `bar` here:
     ///
     /// ```rust
     /// fn foo() -> i32 { 1 }
-    /// let a: fn() -> i32 = foo;
+    /// let bar: fn() -> i32 = foo;
     /// ```
     FnPtr(PolyFnSig<'tcx>),