Miscellaneous documentation additions.

Added notes explaining how [expr, ..expr] form is used, targeted at
individuals like me who thought it was more general and handled
dynamic repeat expressions.  (I left a TODO for this section in a
comment, but perhaps that is bad form for the manual...)

Added example of `do` syntax with a function of arity > 1; yes, one
should be able to derive this from the text above it, but it is still
a useful detail to compare and contrast against the arity == 1 case.

Added example of using for expression over a uint range, since someone
who is most used to write `for(int i; i < lim; i++) { ... }` will
likely want to know how to translate that form (regardless of whether
it happens to be good style or not for their use-case).

Added note about the semi-strange meaning of "fixed size" of vectors
in the vector type section.

1 files changed, 33 insertions, 1 deletions

diff --git a/doc/rust.md b/doc/rust.md
index 60a83662b0e..3dca649807f 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -1671,6 +1671,12 @@ vec_elems : [expr [',' expr]*] | [expr ',' ".." expr]
 A [_vector_](#vector-types) _expression_ is written by enclosing zero or
 more comma-separated expressions of uniform type in square brackets.
 
+In the `[expr ',' ".." expr]` form, the expression after the `".."`
+must be an expression form that can be evaluated at compile time, such
+as a [literal](#literals) or a [constant](#constants).
+
+<!--- TODO: elaborate the actual subgrammar for constant expressions -->
+
 ~~~~
 [1, 2, 3, 4];
 ["a", "b", "c", "d"];
@@ -2156,6 +2162,19 @@ do f |j| {
 }
 ~~~~
 
+In this example, both calls to the (binary) function `k` are equivalent:
+
+~~~~
+# fn k(x:int, f: &fn(int)) { }
+# fn l(i: int) { }
+
+k(3, |j| l(j));
+
+do k(3) |j| {
+   l(j);
+}
+~~~~
+
 
 ### For expressions
 
@@ -2184,7 +2203,7 @@ and early boolean-valued returns from the `block` function,
 such that the meaning of `break` and `loop` is preserved in a primitive loop
 when rewritten as a `for` loop controlled by a higher order function.
 
-An example a for loop:
+An example of a for loop over the contents of a vector:
 
 ~~~~
 # type foo = int;
@@ -2198,6 +2217,14 @@ for v.each |e| {
 }
 ~~~~
 
+An example of a for loop over a series of integers:
+
+~~~~
+# fn bar(b:uint) { }
+for uint::range(0, 256) |i| {
+    bar(i);
+}
+~~~~
 
 ### If expressions
 
@@ -2474,6 +2501,7 @@ fail_unless!(b != "world");
 
 The vector type constructor represents a homogeneous array of values of a given type.
 A vector has a fixed size.
+(Operations like `vec::push` operate solely on owned vectors.)
 A vector type can be annotated with a _definite_ size,
 written with a trailing asterisk and integer literal, such as `[int * 10]`.
 Such a definite-sized vector type is a first-class type, since its size is known statically.
@@ -2484,6 +2512,10 @@ such as `&[T]`, `@[T]` or `~[T]`.
 The kind of a vector type depends on the kind of its element type,
 as with other simple structural types.
 
+Expressions producing vectors of definite size cannot be evaluated in a
+context expecting a vector of indefinite size; one must copy the
+definite-sized vector contents into a distinct vector of indefinite size.
+
 An example of a vector type and its use:
 
 ~~~~