Updating Scarpet docs for BlockIterations.md (#1754)

docs/scarpet/api/BlockIterations.md

@@ -6,13 +6,15 @@ These functions help scan larger areas of blocks without using generic loop func
 
 Evaluates expression over area of blocks defined by its center `center = (cx, cy, cz)`, expanded in all directions 
 by `range = (dx, dy, dz)` blocks, or optionally in negative with `range` coords, and `upper_range` coords in 
-positive values, so you can use that if you know the lower coord, and dimension by calling `'scan(center, 0, 0, 0, w, h, d, ...)`.
+positive values. That means that if you want a box starting at the northwest coord with given base, width and height
+dimensions, you can do `'scan(center, 0, 0, 0, w, h, d, ...)`.
 
 `center` can be defined either as three coordinates, a single tuple of three coords, or a block value.
-`range` and `upper_range` can have the same representations, just if they are block values, it computes the distance to the center
-as range instead of taking the values as is.
+`range` and `upper_range` can have the same representations, just if they are block values, it computes the distance to
+the center as range instead of taking the values as is. That way you can iterate from the center to a box whose surface
+area constains the `range` and/or `upper_range` blocks.
 
-`expr` receives `_x, _y, _z` as coords of current analyzed block and `_`, which represents the block itself.
+`expr` receives `_x, _y, _z` variables as coords of current analyzed block and `_`, which represents the block itself.
 
 Returns number of successful evaluations of `expr` (with `true` boolean result) unless called in void context, 
 which would cause the expression not be evaluated for their boolean value.
@@ -36,19 +38,26 @@ Returns the list of 6 neighbouring blocks to the argument. Commonly used with ot
 for(neighbours(x,y,z),air(_)) => 4 // number of air blocks around a block
 </pre>
 
-### `rect(centre, range?, upper_range?)`
+### `rect(center, range?, upper_range?)`
 
 Returns an iterator, just like `range` function that iterates over a rectangular area of blocks. If only center
-point is specified, it iterates over 27 blocks. If `range` arguments are specified, expands selection by the  respective 
-number of blocks in each direction. If `positive_range` arguments are specified,
- it uses `range` for negative offset, and `positive_range` for positive.
+point is specified, it iterates over 27 blocks (range of 1). If `range` arguments are specified, expands selection by
+the respective number of blocks in each direction. If `upper_range` arguments are specified, it uses `range` for
+negative offset, and `upper_range` for positive, similar to `scan`.
 
-`centre` can be defined either as three coordinates, a list of three coords, or a block value.
-`range` and `positive_range` can have the same representations, just if they are block values, it computes the distance to the center
+Basically the arguments are the same as the first three arguments of `scan`, except this function returns the list of
+blocks that `scan` would evaluate over. If you are going to iterate over these blocks, like `for(rect(args), do_something())`,
+then `scan(args, do_something())` is an equivalent, yet more compute-friendly alternative, especially for very large areas.
+
+`center` can be defined either as three coordinates, a list of three coords, or a block value.
+`range` and `upper_range` can have the same representations, just if they are block values, it computes the distance to the center
 as range instead of taking the values as is.`
 
-### `diamond(centre_pos, radius?, height?)`
+### `diamond(center_pos, radius?, height?)`
 
 Iterates over a diamond like area of blocks. With no radius and height, its 7 blocks centered around the middle 
 (block + neighbours). With a radius specified, it expands shape on x and z coords, and with a custom height, on y. 
 Any of these can be zero as well. radius of 0 makes a stick, height of 0 makes a diamond shape pad.
+
+If radius and height are the same, creats a 3D diamond, of all the blocks which are a manhattan distance of `radius` away
+from the center.