Tutorial doc

src/doc/guide-tasks.md

@@ -101,6 +101,8 @@ fn print_message() { println!("I am running in a different task!"); }
 spawn(print_message);
 
 // Print something more profound in a different task using a lambda expression
+// This uses the proc() keyword to assign to spawn a function with no name
+// That function will call println!(...) as requested
 spawn(proc() println!("I am also running in a different task!") );
 ~~~~
 

src/doc/tutorial.md

@@ -1717,23 +1717,35 @@ environment (sometimes referred to as "capturing" variables in their
 environment). For example, you couldn't write the following:
 
 ~~~~ {.ignore}
-let foo = 10;
+let x = 3;
 
-fn bar() -> int {
-   return foo; // `bar` cannot refer to `foo`
-}
+// `fun` cannot refer to `x`
+fn fun() -> () { println!("{}", x); }
 ~~~~
 
-Rust also supports _closures_, functions that can access variables in
-the enclosing scope.
+A _closure_ does support accessing the enclosing scope; below we will create
+2 _closures_ (nameless functions). Compare how `||` replaces `()` and how
+they try to access `x`:
 
-~~~~
-fn call_closure_with_ten(b: |int|) { b(10); }
+~~~~ {.ignore}
+let x = 3;
+
+// `fun` is an invalid definition
+fn  fun       () -> () { println!("{}", x) }  // cannot capture enclosing scope
+let closure = || -> () { println!("{}", x) }; // can capture enclosing scope
+
+// `fun_arg` is an invalid definition
+fn  fun_arg       (arg: int) -> () { println!("{}", arg + x) }  // cannot capture enclosing scope
+let closure_arg = |arg: int| -> () { println!("{}", arg + x) }; // can capture enclosing scope
+//                       ^
+// Requires a type because the implementation needs to know which `+` to use.
+// In the future, the implementation may not need the help.
 
-let captured_var = 20;
-let closure = |arg| println!("captured_var={}, arg={}", captured_var, arg);
+fun();          // Still won't work
+closure();      // Prints: 3
 
-call_closure_with_ten(closure);
+fun_arg(7);     // Still won't work
+closure_arg(7); // Prints: 10
 ~~~~
 
 Closures begin with the argument list between vertical bars and are followed by
@@ -1742,13 +1754,41 @@ considered a single expression: it evaluates to the result of the last
 expression it contains if that expression is not followed by a semicolon,
 otherwise the block evaluates to `()`.
 
-The types of the arguments are generally omitted, as is the return type,
-because the compiler can almost always infer them. In the rare case where the
-compiler needs assistance, though, the arguments and return types may be
-annotated.
+Since a closure is an expression, the compiler can usually infer the argument and
+return types; so they are often omitted. This is in contrast to a function which
+is a declaration and _not_ an expression. Declarations require the types to be
+specified and carry no inference. Compare:
+
+~~~~ {.ignore}
+// `fun` cannot infer the type of `x` so it must be provided because it is a function.
+fn  fun       (x: int) -> () { println!("{}", x) };
+let closure = |x     | -> () { println!("{}", x) };
+
+fun(10);     // Prints 10
+closure(20); // Prints 20
+
+fun("String"); // Error: wrong type
+// Error: This type is different from when `x` was originally evaluated
+closure("String");
+~~~~
+
+The null arguments `()` are typically dropped so the end result
+is more compact.
+
+~~~~
+let closure = |x| { println!("{}", x) };
+
+closure(20); // Prints 20
+~~~~
+
+Here, in the rare case where the compiler needs assistance,
+the arguments and return types may be annotated.
 
 ~~~~
 let square = |x: int| -> uint { (x * x) as uint };
+
+println!("{}", square(20));  // 400
+println!("{}", square(-20)); // 400
 ~~~~
 
 There are several forms of closure, each with its own role. The most