Docs.

modules/monkey/newdocs/language/arrays.md

@@ -5,13 +5,13 @@
 
 An array is a linear sequence of values that can be addressed using one or more integer indices.
 
-Each array has an associated element type. That is, the type of the values actually stored in the array. An array's element type is a purely static property. It is only known at compile time so arrays cannot be 'downcast' at runtime.
+Each array has an associated element type. That is, the type of the values actually stored in the array. An array's element type is a purely static property. It is only known at compile time so arrays cannot be 'cast' to different array types at runtime.
 
-The syntax used for declaring values and variables of array type is: 
+Array variables are declared using the syntax:
 
-_ElementType_ `[` [`,`...] `]`
+_ElementType_`[`[`,`...]`]`
 
-An array can also be multidimensional, in which case the '[]' will contain 1 or more commas.
+An array can be multidimensional, in which case the '[]' will contain 1 or more commas.
 
 Here are some example of declaring array variables:
 
@@ -24,13 +24,13 @@ Local stacks:Stack<Int>[]	'One dimensional array of stacks of type Int.
 
 @#### Creating arrays
 
-Declaring an array does not actually create an array. To do that you must use `New`.
+Declaring an array does not actually create an array. To do that you must use the `New` operator.
 
 `New` can be used to create either a null intialized or value initialized array. The syntax for creating a null initialized array is:
 
 `New` _ElementType_ `[` _Sizes_ `]`
 
-...where sizes is a comma separated sequence of dimension size.
+...where sizes is a comma separated sequence of dimension sizes.
 
 The syntax for creating a value initialized array is:
 
@@ -80,8 +80,8 @@ Local ints:=New Int[]( 1,2,3 )
 ints=ints.Resize( 5 )	'ints now contains 1,2,3,0,0
 ```
 
-(Note that resize does not actually resize the array! It actually returns a resized *copy* of the array.)
+Note that resize actually returns a resized *copy* of the input array. The input array is not modified in any way.
 
-Note that mutidimensional arrays cannot currently be sliced or resized, and you cannot create an initialized multidimensional arrays. These features are planned for the future though.
+Multidimensional arrays cannot currently be sliced or resized.
 
 For more information, see the [[types.Array.Resize|Array.Resize]] API documentation.

modules/monkey/newdocs/language/enums.md

@@ -3,56 +3,33 @@
 
 ### Enums
 
-`Enum` is a data type containing a set of Int constants.
+An enum is a user defined data type that contains a set of named integer constants. Enums are frequently used to implement typesafe 'flags' or 'bitmasks'.
 
-By default the members will receive values starting from zero and incemented by one for each new member. You can assign a chosen value to each member when declaring them.
+Unintialized enum members are automatically assigned constant integer values starting with 0 and increasing by 1 for each successive enum member:
 
 ```
-Enum myBasicEnum
-	a,b,c 'a=0, b=1, c=2
+Enum MyEnum
+	A,B,C			'A, B, C will be assigned the values 0, 1, 2.
+	D,E,F			'D, E, F will be assigned the values 4, 5, 6.
 End
 ```
-```
-Enum myCustomEnum
-	a=7
-	b=31,c,d 'c=32, d=33
-End
-```
-The values can be accessed with the postfix member acces operator (`.`).
-Enums values are implicitly converted to integral values when assigned to it.
-```
-Local i:UInt=myCustomEnum.b
-```
-
-You can also create `Enum` variables. An `Enum` variable contains an Int variable in addition to it's constant members (default value is zero).
 
-Bitwise operators (|,&,~) can be used with Enums variables and Enums members to compute combinations. Such Enums most often contain powers of 2 numbers as members! (1,2,4,8,16,32,64,... and 0 if needed).
+You can also initialize enum members with a constant integer value:
 
-A bitmask Enum example:
-```
-Enum Flags 'a classic Enum. (4 bits bitmask)
-	None=0
-  A=$0001 'bin OOOI dec 1
-  B=$0002 'bin OOIO dec 2
-  C=$0004 'bin OIOO dec 4
-  D=$0008 'bin IOOO dec 8
-End
-```
-An enum with modifiers example (in this case the bitwise operators should be used with at least one modifier):
 ```
-Enum Foo '(modifiers on 5th and 6th bit)
-	None=0
-	A=1,B,C,D,E,F,G,H,J,K,L,M ' max 15 because the 5th bit is used for modifier
-	Modifier_A=$0010 'bin IOOOO dec 16
-	Modifier_B=$0020 'bin IOOOOO dec 32
+Enum MyEnum
+	A=10,B=20,C=30	'A, B, C will be assigned the values 10,20,30
+	D,E,F			'D, E, F will be assigned the values 31, 32, 33.
 End
 ```
 
-For now enums don't accept negative number literals. To assign a negative number you'll have to type a substraction until the bug is resolved.
+Enum members are accessed using the 'dot' operator:
+
 ```
-Enum Foo '(with a negative member)
-	Negative=0-1 'instead of -1
-	None=0
-	A=1,B,C,D,E,F,G,H,J,K,L,M
-End
+Local e:MyEnum=MyEnum.A
 ```
+
+Enum values can be implictly converted to any integer type, and can be used with the `&` (bitwise 'and'), `|` (bitwise 'or') and `~` (bitwise 'exclusive-or') binary operators. This allows you to use enums to represent 'bitmasks'.
+
+Enum values can also be compared with enum values of the same type, or with a `Null` which represents an enum value with the integer value 0.
+

modules/monkey/newdocs/language/strings.md

@@ -3,15 +3,9 @@
 
 ### Strings
 
-Values of type String are used to represent sequences of characters, such as text. The exact size of each character in a string value is target dependent, but is at least 8 bits.
+A String is an immutable sequence of 16 bit characters that is usually used to represent text.
 
-String variables are declared using the type name `String`, for example:
-
-```
-Local test:String="Hello World"
-```
-
-String literals are sequences of characters enclosed in "" (quotation marks). String literals may also include escape sequences, special sequences of characters used to represent unprintable characters.
+String literals are sequences of characters enclosed in `"``"` (quotation marks). String literals may also include escape sequences, special sequences of characters used to represent unprintable characters.
 
 You can use the following escape sequences in string literals:
 
@@ -24,13 +18,30 @@ You can use the following escape sequences in string literals:
 |~z					| 0 (null)
 |~~	 				| 126 (tilde ~)
 
-For example, to include literal quotation marks in a string...
+For example, to include literal quotation marks in a string:
 
 ```
 Local test:="~qHello World~q" 
 ```
 
-You can index a string using the `[]' operator, eg:
+Strings can also be declared across multiple lines:
+
+```
+Const multiLine:="
+Multi Line String
+"
+```
+
+In this case, each newline inside the quote marks is simply included in the string, so the above example string actually contains 2 'hidden' newlines.
+
+String variables are declared using the type name `String`, for example:
+
+```
+Local test:String="Hello World"
+```
+
+You can index a string using the `[]' operator:
+
 ```
 Local str:="Hello World"
 For Local i:=0 Until str.Length
@@ -40,7 +51,7 @@ Next
 
 Indexing a string will return the character code at a given string index as an int.
 
-You can iterate through the characters in a string using `Eachin`, eg:
+You can iterate through the characters in a string using `Eachin`:
 
 ```
 For Local chr:=Eachin "Hello World"
@@ -48,4 +59,4 @@ For Local chr:=Eachin "Hello World"
 Next
 ```
 
-For more information on strings, please see the [[types.String|String]] API reference.
+Strings have a number of useful methods including [[types.String.Slice|Slice]], [[types.String.Find|Find]] and [[types.String.Split|Split]]. For more information on strings, please see the [[types.String|String]] API reference.

modules/monkey/newdocs/language/types.md

@@ -7,7 +7,7 @@
 
 The following primtive types are supported:
 
-| Type		| Description
+| Type Name	| Description
 |:----------|:-----------
 | `Void`	| No type.
 | `Bool`	| Boolean type.
@@ -24,32 +24,35 @@ The following primtive types are supported:
 | `String`	| String of 16 bit characters.
 | `Object`	| Base type of all objects.
 
+
 @#### Compound types
 
 The following compound types are supported:
 
-| Type						| Description
-|:--------------------------|:-----------
-| _Type_ `[` [,...] `]`		| Array type
-| _Type_ `Ptr`				| Pointer type
-| _Type_ `(` _Types_ `)`	| Function type
+| Type Syntax							| Description
+|:--------------------------------------|:-----------
+| _ElementType_`[]`						| Array type.
+| _PointeeType_ `Ptr`					| Pointer type.
+| _ReturnType_`(`_ParameterTypes_`)`	| Function type.
+
+Array types can have more than one dimension, for example: `[,]` declares a 2D array, `[,,]` declares a 3D array and so on.
+
+The parameter types for a function type can optionally include an identifier prefix, for example: `MyFunction:Int( arg:Int )`. The prefix must be a valid identifier but is otherwise ignored.
 
 
 @#### Implicit type conversions
 
 These type conversions are performed automatically:
 
-| Source type					| Destination type
-|:------------------------------|:-----------------
-| Any numeric type	 			| `Bool`
-| String or array type 			| `Bool`
-| Class or interface type	 	| `Bool`
-| Any numeric type				| Any numeric type
-| Any numeric type or `Bool`	| `String`
-| Any pointer type				| `Void Ptr`
-| Any enum type					| Any integral type
-| Class or interface type		| Base class type or implemented interface type
-| Class, interface or struct type | `Bool`
+| Source type						| Destination type
+|:----------------------------------|:-----------------
+| `Bool`							| `String`
+| Any numeric type					| `Bool`, `String` or any numeric type.
+| `String` or any array type 		| `Bool`
+| Any pointer type					| `Void Ptr`
+| Class, interface or struct type	| `Bool`
+| Class or interface type			| Base class or implemented interface type
+| Enum type							| `Bool` or any integral type.
 
 When numeric values are converted to bool, the result will be true if the value is not equal to 0.
 
@@ -57,24 +60,37 @@ When strings and arrays are converted to bool, the result will be true if the le
 
 When class or interface instances are converted to bool, the result will be true if the instance is not equal to null.
 
-When struct values are converted, the result will be true if the struct value is not equal to null.
+When struct values are converted to bool, the result will be true if the struct value is not equal to null.
+
+When floating point values are converted to integral values, the fractional part of the floating point value is chopped off - no rounding is performed.
 
-When floating point values are converted to integral values, the fractional part of the floating point value is simply chopped off - no rounding is performed.
+When bools are converted to strings, the result will be either "True" or "False".
 
-When Bools are converted to strings, the result will be either "True" or "False".
 
+@#### Explicit type conversions 
 
-@#### Explicit type conversions
+Some type conversions must be explicitly performed using the 'cast' operator. The cast operator has the syntax:
 
-The `Cast` `<` _dest-type_ `>` `:` _dest-type_ `(` _expression_ `)` operator must be used for these type conversions:
+`Cast<`_DestinationType_`>:`_DestinationType_`(`_SourceExpression_`)`
+
+You must use the cast operator to perform the following type conversions:
 
 | Source type			| Destination type
 |:----------------------|:-----------------
 | `Bool`				| Any numeric type
 | `String`				| Any numeric type
-| Any pointer type		| Any pointer type, any integral type
-| Any integral type		| Any pointer type, any enum type
-| Class type			| Derived class type, any interface type
-| Interface type		| Any class type, any interface type
+| Any pointer type		| Any pointer type or any integral type
+| Any integral type		| Any pointer type or any enum type.
+| Class type			| Derived class or any interface type.
+| Interface type		| Any class or interface type.
+
+When using the cast operator to dynamically downcast an object or interface instance, the result will be `Null` if the cast failed.
 
 When casting bool values to a numeric type, the result will be 1 for true, 0 for false.
+
+You can also use 'function syntax' to explictly cast values to primitive types:
+
+```
+Local floatValue:Float=3.14
+Local intValue:=Int( floatValue )
+```

modules/monkey/newdocs/language/variants.md

@@ -3,7 +3,7 @@
 
 ### Variants
 
-The Variant type is a primitive type that can be used to 'box' values of any type.
+A Variant is a special value that can be used to 'box' values of any other type.
 
 The easiest way to create a variant is to cast a value to Variant (much like casting an Int to String etc), eg:
 
@@ -17,7 +17,7 @@ v=10				'variant now contains an int 10.
 v="hello"			'variant now contains a string "hello".
 ```
 
-A variant is 'true' if it contains any value with a non-void type (including a bool false value!) and 'false' if it is uninitialized and has no (void) type.
+A variant is true if it is initialized (even if it contains a bool 'false' value) and false if it is uninitialized. There is currently no way to uninitialize a variant, so once a variant is initialized it will always be 'true'.
 
 Any type of value can be implicitly converted to a variant, so you can easily pass anything to a function with variant parameters:
 
@@ -47,4 +47,6 @@ Local v:=Variant( 10 )
 Print Cast<String>( v )	'Runtime error! Variant contains an Int not a String!
 ```
 
-The one exception to this is if the Variant contains a class object, in which case you can cast the variant to any valid base class of the object.
+The one exception to this is if the variant contains a instance of an object, in which case you can cast the variant to any valid base class of the object's actual type.
+
+Variants also have a number of useful methods including...