Update documentation

CHANGELOG.md

@@ -12,6 +12,12 @@
 
 * Added `MILLFORK_VERSION` preprocessor parameter.
 
+* Added structs.
+
+* Pointers can now be allocated anywhere.
+
+* Arrays can now have elements of types other than `byte` (still limited in size to 1 byte though).
+
 * Added hint for identifiers with typos.
 
 * Aliases now also support subfields.

docs/abi/variable-storage.md

@@ -12,10 +12,10 @@ Variables in Millfork can belong to one of the following storage classes:
 
 * parameter: function parameters
 
-Variables can also belong to one of the following memory segments 
+Variables can also belong to one of the following memory areas 
 (unless overridden with the `@` operator):
 
-* zeropage: all `pointer` variables and parameters
+* zeropage: all `pointer` variables and parameters with no defined memory segment (6502-like targets only)
 
 * high RAM: all the other variables and parameters
 

docs/lang/syntax.md

@@ -57,6 +57,12 @@ For every variable `x` larger than a byte, extra subvariables are defined:
     * constituent bytes, from low to high: `x.b0`, `x.b1`, `x.b2`, `x.b3`
     
     * partial words: `x.loword` (=`x.b1:x.b0`), `x.hiword` (=`x.b3:x.b2`)
+    
+* if `x` is of a larger integral type:
+
+    * constituent bytes, from low to high: `x.b0`, `x.b1`, `x.b2`, etc.
+    
+    * the lowest word: `x.loword` (=`x.b1:x.b0`)
 
 ### Constant declarations
 
@@ -100,12 +106,16 @@ An array is a continuous sequence of bytes in memory.
 
 Syntax:
 
-`[segment(<segment>)] array <name> [[<size>]] [align ( <alignment> )] [@<address>] [= <initial_values>]`
+`[segment(<segment>)] array [(<element type>)] <name> [[<size>]] [align ( <alignment> )] [@<address>] [= <initial_values>]`
 
 * `<segment>`: segment name; if absent,
 then defaults to `default_code_segment` as defined for the platform if the array has initial values,
 or to `default` if it doesn't.
 
+* `<element type>`: type of the elements of the array.
+It must be of size 1 byte.
+If omitted, the default is `byte`.
+
 * `<size>`: either a constant number, which then defines the size of the array,
 or a name of a plain enumeration type, in which case changes the type of the index to that enumeration
 and declares the array size to be equal to the number of variants in that enumeration.

docs/lang/types.md

@@ -87,3 +87,31 @@ Plain enumerations have their variants equal to `byte(0)` to `byte(<name>.count
     
 Tip: You can use an enumeration with no variants as a strongly checked alternative byte type,
 as there are no checks no values when converting bytes to enumeration values and vice versa.
+
+## Structs
+
+Struct is a compound type containing multiple fields of various types:
+
+    struct <name> { <field definitions (type and name), separated by commas or newlines>}
+
+A struct is represented in memory as a contiguous area of variables laid out one after another.
+
+Struct can have a maximum size of 255 bytes. Larger structs are not supported.
+
+You can access a field of a struct with the dot:
+
+    struct point { word x, word y }
+    
+    point p
+    p.x = 3
+    p.y.lo = 4
+
+Offsets are available as `structname.fieldname.offset`:
+
+    pointer ptr
+    ptr = p.addr
+    ptr += point.y.offset
+    // ptr points now at p.y
+    
+    // alternatively:
+    ptr = p.y.addr