docs(manual): tighten prose and reorganize reference 📚

Author: timfennis

manual/src/SUMMARY.md

@@ -20,11 +20,11 @@
   - [Deque](./reference/types/deque.md): A double ended queue
   - [MinHeap & MaxHeap](./reference/types/min-max-heap.md): Min/max Heap
   - [Function](./reference/types/function.md)
-
-- [If-else](./reference/if-else.md)
-- [While loop](./reference/while-loop.md)
-- [For loops and comprehensions](./reference/for-loop.md)
-- [Functions](./reference/functions.md)
+- [Control flow](./reference/control-flow.md)
+  - [If-else](./reference/if-else.md)
+  - [While loop](./reference/while-loop.md)
+  - [For loops and comprehensions](./reference/for-loop.md)
+  - [Logical operators](./reference/logical-operators.md)
 - [Memory Management](./reference/memory-management.md)
 
 # Features

manual/src/features/augmented-assignment.md

@@ -1,8 +1,8 @@
 # Augmented assignment
 
-In Andy C++ you can augment assignment operators to quickly perform operations on existing variables like you might expect from any language.
+Andy C++ supports augmented assignment for operations on existing variables.
 
-In this example we're augmenting the assignment operator with another operator to quickly increment a number.
+This example increments a number with augmented assignment.
 
 ```
 let my_number = 3;
@@ -13,15 +13,13 @@ assert_eq(my_number, 8);
 
 ## Optimization
 
-You might expect `list ++= [1,2,3]` desugar to something like `list = list ++ [1,2,3]` but this would be needlessly inefficient. This is why
-languages like Andy C++ have special handling for some of these assignment operators. For instance the earlier example simply appends `[1,2,3]` to
-list without creating an intermediary list first.
+You might expect `list ++= [1,2,3]` to desugar to `list = list ++ [1,2,3]`, but that would waste work. Andy C++ handles some augmented assignments directly. In this case, it appends `[1,2,3]` without creating an intermediate list.
 
 ## Flexibility
 
 Note: I stole this feature from [Noulith](https://github.com/betaveros/noulith).
 
-Augmented assignment is not limited to built in operators, you can also use built in function or user created functions to augment assignment. Consider the following example:
+Augmented assignment also works with built-in functions and user-defined functions. For example:
 
 ```ndc
 let x = 3;
@@ -30,7 +28,7 @@ x f= 5; // similar to: x = f(x, 5);
 assert_eq(x, 8);
 ```
 
-A common situation where you might want to use is when finding the highest or lowest value in an iteration:
+One common use case is tracking the highest or lowest value in a loop:
 
 ```ndc
 let lowest, highest = Inf, -Inf;

manual/src/features/memoization.md

@@ -1,12 +1,10 @@
 # Memoization
 
-Andy C++ natively supports memoization through the `pure` keyword. Declaring a function as `pure` indicates that
-it has no side effects and always produces the same output for the same inputs. This allows the language to
-automatically cache and reuse results, improving performance for repeated calls with the same arguments.
+Andy C++ supports memoization through the `pure` keyword. Mark a function as `pure` when it has no side effects and returns the same output for the same inputs. Andy C++ can then cache and reuse previous results.
 
 ### Syntax
 
-You can mark both named and anonymous functions as `pure`:
+Mark both named and anonymous functions as `pure`:
 
 ```ndc
 pure fn add(x, y) {
@@ -16,18 +14,15 @@ pure fn add(x, y) {
 let multiply = pure fn (x, y) { x * y };
 ```
 
-> **Note:** the interpreter does not perform any checks to see if the function is actually pure. It's your
-> responsibility to ensure that functions don't have side-effects.
+> **Note:** The interpreter does not check whether a function is actually pure. You must avoid side effects yourself.
 
 ### Performance: keep memoization keys small
 
 The cache key is computed by hashing **all arguments**. For container types like maps and lists this
 is an O(n) operation proportional to the number of elements. Passing large containers as arguments
-to a `pure fn` therefore adds hashing overhead on every call — even on cache hits.
+to a `pure fn` therefore adds hashing overhead on every call, even on cache hits.
 
-If a container is large and doesn't change between recursive calls (e.g. a lookup table or graph),
-capture it as an **upvalue** instead of passing it as an argument. The upvalue is not part of the
-cache key, so the memoization cost is proportional only to the arguments that actually vary.
+If a container is large and does not change between recursive calls, such as a lookup table or graph, capture it as an **upvalue** instead of passing it as an argument. The upvalue is not part of the cache key, so memoization cost depends only on the arguments that change.
 
 ```ndc
 // Slow: `graph` is hashed on every call

manual/src/features/method-call-syntax.md

@@ -7,10 +7,10 @@
 ```ndc
 let l = [50, 40, 20, 40, 10];
 
-// Usually you might write something like this
+// A plain function-call version
 let x = reduce(map(sorted(l), fn(x) => x + 5), fn(a, b) => a * b);
 
-// It's much easier to read and write this type of code using method call syntax
+// The same code with method call syntax
 let y = l.sorted
          .map(fn(x) => x + 5)
          .reduce(fn(a, b) => a * b);

manual/src/reference/control-flow.md

@@ -0,0 +1,3 @@
+# Control flow
+
+Control flow in Andy C++ uses expressions and keywords instead of punctuation-heavy syntax. This section covers branching, loops, and the lazy logical operators that often appear in conditions.

manual/src/reference/for-loop.md

@@ -1,6 +1,6 @@
 # For loop
 
-For loops are where Andy C++ gets a little spicier. First let's look at some basic examples:
+Start with a basic `for` loop:
 
 ```ndc
 for n in 1..=100 {
@@ -16,7 +16,7 @@ for n in 1..=100 {
 }
 ```
 
-You can combine multiple iterations in a single loop:
+You can combine multiple iterators in one loop:
 
 ```ndc
 let drinks = ["Coffee", "Tea", "Juice"];
@@ -28,7 +28,7 @@ for drink in drinks, dessert in desserts {
 }
 ```
 
-Finally you can also add one or more guards. The example below finds all pairs of numbers from 1 until 10 that have an even sum.
+You can also add one or more guards. This example finds all pairs from `1..10` with an even sum.
 
 ```ndc
 for x in 1..10, y in 1..10, if (x + y) % 2 == 0 {
@@ -38,16 +38,16 @@ for x in 1..10, y in 1..10, if (x + y) % 2 == 0 {
 
 ## For comprehensions
 
-The same features, using a similar syntax, can also be used to produce lists on the go using list comprehensions.
+You can use the same syntax in a list comprehension.
 
 ```ndc
-// To produce a series fo perfect squares
+// Produce a series of perfect squares
 let perfect_squares = [x * x for x in 1..10];
 
 assert_eq([1,4,9,16,25,36,49,64,81,100], perfect_squares);
 ```
 
-Once again the earlier example can be used to produce actual pairs as follows:
+The earlier example can also produce pairs:
 
 ```ndc
 let pairs_with_even_sum = [x, y for x in 1..10, y in 1..10, if (x + y) % 2 == 0]

manual/src/reference/functions.md

@@ -0,0 +1,47 @@
+# Logical operators
+
+Andy C++ uses the keywords `and`, `or`, and `not` for logical operators. If you are coming from Rust, write `and` and `or` instead of `&&` and `||`.
+
+```ndc
+let ready = has_input and not failed;
+let retry = timed_out or disconnected;
+```
+
+## Short-circuiting
+
+`and` and `or` are lazy. Andy C++ evaluates the right-hand side only when it needs that value to decide the result.
+
+```ndc
+let x = 0;
+
+true and { x = x + 1; false };
+false and { x = x + 1; false };
+true or { x = x + 1; false };
+false or { x = x + 1; false };
+
+assert_eq(x, 2);
+```
+
+`false and ...` stops at `false`, and `true or ...` stops at `true`.
+
+## Precedence
+
+`and` binds tighter than `or`.
+
+```ndc
+let a = true or true and false;  // true
+let b = false and true or true;  // true
+```
+
+That means Andy C++ reads those expressions as:
+
+```ndc
+let a = true or (true and false);
+let b = (false and true) or true;
+```
+
+## Bitwise operators
+
+Boolean values also support the non-lazy operators `&`, `|`, and `~`.
+
+Use `and` and `or` when you want short-circuiting. Use `&` and `|` when you need both sides to run.

manual/src/reference/logical-operators.md

@@ -17,24 +17,4 @@ Operators defined for booleans:
 | `and` | lazy logical and |
 | `not` | logical not like `!` but lower precedence |
 
-## Lazy evaluation of `and` and `or`
-
-The `and` and `or` operators are **lazy**, meaning their operands are evaluated only when necessary to determine the result.
-This differs from bitwise operators (`|`, `&`, `~`), which always evaluate both operands.
-
-```ndc
-fn a() {
-    print("a invoked");
-    false
-};
-
-fn b() {
-    print("b invoked");
-    true
-};
-
-// Only "a invoked" is printed because evaluation is lazy.
-if a() and b() {
-    // ...
-}
-```
+See [Logical operators](../logical-operators.md) for short-circuiting and precedence rules.