---

yaml
---
r: 62543
b: refs/heads/snap-stage3
c: b71a1ec
h: refs/heads/master
i:
  62541: 11829c3
  62539: c60b062
  62535: dc9a0b7
  62527: a655b93
v: v3

Author: jbclements

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 2d28d645422c1617be58c8ca7ad9a457264ca850
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 999f6926459294136b623b101c8a033ec8ec29db
+refs/heads/snap-stage3: b71a1ecea2de87cff3089f9f261be71cd314aac9
 refs/heads/try: 7b78b52e602bb3ea8174f9b2006bff3315f03ef9
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/doc/rust.md

@@ -2250,6 +2250,14 @@ do_expr : "do" expr [ '|' ident_list '|' ] ? '{' block '}' ;
 A _do expression_ provides a more-familiar block-syntax for a [lambda expression](#lambda-expressions),
 including a special translation of [return expressions](#return-expressions) inside the supplied block.
 
+Any occurrence of a [return expression](#return-expressions)
+inside this `block` expression is rewritten
+as a reference to an (anonymous) flag set in the caller's environment,
+which is checked on return from the `expr` and, if set,
+causes a corresponding return from the caller.
+In this way, the meaning of `return` statements in language built-in control blocks is preserved,
+if they are rewritten using lambda functions and `do` expressions as abstractions.
+
 The optional `ident_list` and `block` provided in a `do` expression are parsed as though they constitute a lambda expression;
 if the `ident_list` is missing, an empty `ident_list` is implied.
 
@@ -2296,19 +2304,15 @@ A _for expression_ is similar to a [`do` expression](#do-expressions),
 in that it provides a special block-form of lambda expression,
 suited to passing the `block` function to a higher-order function implementing a loop.
 
-Like a `do` expression, a `return` expression inside a `for` expresison is rewritten,
-to access a local flag that causes an early return in the caller.
-
-Additionally, any occurrence of a [return expression](#return-expressions)
-inside the `block` of a `for` expression is rewritten
-as a reference to an (anonymous) flag set in the caller's environment,
-which is checked on return from the `expr` and, if set,
-causes a corresponding return from the caller.
-In this way, the meaning of `return` statements in language built-in control blocks is preserved,
-if they are rewritten using lambda functions and `do` expressions as abstractions.
+In contrast to a `do` expression, a `for` expression is designed to work
+with methods such as `each` and `times`, that require the body block to
+return a boolean. The `for` expression accommodates this by implicitly
+returning `true` at the end of each block, unless a `break` expression
+is evaluated.
 
-Like `return` expressions, any [`break`](#break-expressions) and [`loop`](#loop-expressions) expressions
-are rewritten inside `for` expressions, with a combination of local flag variables,
+In addition, [`break`](#break-expressions) and [`loop`](#loop-expressions) expressions
+are rewritten inside `for` expressions in the same way that `return` expressions are,
+with a combination of local flag variables,
 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.