Improve writeup.

doc/src/language/for.md

@@ -3,7 +3,8 @@
 
 {{#include ../links.md}}
 
-Iterating through a range or an [array] is provided by the `for` ... `in` loop.
+Iterating through a range or an [array], or any type with a registered _iterator_,
+is provided by the `for` ... `in` loop.
 
 Like C, `continue` can be used to skip to the next iteration, by-passing all following statements;
 `break` can be used to break out of the loop unconditionally.

doc/src/language/if.md

@@ -19,6 +19,9 @@ if foo(x) {
 }
 ```
 
+Braces Are Mandatory
+--------------------
+
 Unlike C, the condition expression does _not_ need to be enclosed in parentheses '`(`' .. '`)`', but
 all branches of the `if` statement must be enclosed within braces '`{`' .. '`}`',
 even when there is only one statement inside the branch.

doc/src/language/logic.md

@@ -65,42 +65,3 @@ a() | b();              // both a() and b() are evaluated
 
 a() & b();              // both a() and b() are evaluated
 ```
-
-Compound Assignment Operators
-----------------------------
-
-```rust
-let number = 9;
-
-number += 8;            // number = number + 8
-
-number -= 7;            // number = number - 7
-
-number *= 6;            // number = number * 6
-
-number /= 5;            // number = number / 5
-
-number %= 4;            // number = number % 4
-
-number ~= 3;            // number = number ~ 3
-
-number <<= 2;           // number = number << 2
-
-number >>= 1;           // number = number >> 1
-
-number &= 0x00ff;       // number = number & 0x00ff;
-
-number |= 0x00ff;       // number = number | 0x00ff;
-
-number ^= 0x00ff;       // number = number ^ 0x00ff;
-```
-
-The `+=` operator can also be used to build [strings]:
-
-```rust
-let my_str = "abc";
-my_str += "ABC";
-my_str += 12345;
-
-my_str == "abcABC12345"
-```

doc/src/language/method.md

@@ -4,8 +4,8 @@ Call Method as Function
 {{#include ../links.md}}
 
 
-First `&mut` Reference Parameter
--------------------------------
+First `&mut` Parameter
+----------------------
 
 Property [getters/setters] and [methods][custom types] in a Rust custom type registered with the [`Engine`] can be called
 just like a regular function.  In fact, like Rust, property getters/setters and object methods
@@ -37,19 +37,20 @@ array[0].update();  // <- call in method-call style will update 'a'
 ```
 
 
-Encouraged Usage
-----------------
+`&mut` is Efficient
+------------------
 
 Using a `&mut` first parameter is highly encouraged when using types that are expensive to clone,
 even when the intention is not to mutate that argument, because it avoids cloning that argument value.
 
-For primary types that are cheap to clone, including `ImmutableString`, this is not necessary.
+For primary types that are cheap to clone (e.g. those that implement `Copy`),
+including `ImmutableString`, this is not necessary.
 
 
 Avoid `&mut ImmutableString`
 ---------------------------
 
-`ImmutableString`, Rhai internal [string] type, is an exception.
+`ImmutableString`, Rhai's internal [string] type, is an exception.
 
 `ImmutableString` is cheap to clone, but expensive to take a mutable reference (because the underlying
 string must be cloned to make a private copy).

doc/src/language/other-op.md

@@ -0,0 +1,66 @@
+Other Operators
+===============
+
+{{#include ../links.md}}
+
+
+Compound Assignment Operators
+----------------------------
+
+```rust
+let number = 9;
+
+number += 8;            // number = number + 8
+
+number -= 7;            // number = number - 7
+
+number *= 6;            // number = number * 6
+
+number /= 5;            // number = number / 5
+
+number %= 4;            // number = number % 4
+
+number ~= 3;            // number = number ~ 3
+
+number <<= 2;           // number = number << 2
+
+number >>= 1;           // number = number >> 1
+
+number &= 0x00ff;       // number = number & 0x00ff;
+
+number |= 0x00ff;       // number = number | 0x00ff;
+
+number ^= 0x00ff;       // number = number ^ 0x00ff;
+```
+
+
+The Flexible `+=`
+----------------
+
+The `+=` operator can also be used to build [strings]:
+
+```rust
+let my_str = "abc";
+my_str += "ABC";
+my_str += 12345;
+
+my_str == "abcABC12345"
+```
+
+It may also be used to concatenate [arrays]:
+
+```rust
+let my_array = [1, 2, 3];
+my_array += [4, 5];
+
+my_array == [1, 2, 3, 4, 5];
+```
+
+or mix two [object maps] together:
+
+```rust
+let my_obj = #{a:1, b:2};
+my_obj += #{c:3, d:4, e:5};
+
+my_obj.len() == 5;
+```