Update documentation

 * Add ByREF
 * Add ByVal
 * Update Function

Author: boriel

docs/byref.md

@@ -0,0 +1,75 @@
+#ByREF
+
+`ByRef` is a modifier used in function parameters to specify that the parameters is passed by reference (that is, 
+the original variable is passed to the [FUNCTION](function.md) or [SUB](sub.md)).
+
+##Syntax
+
+It's used in function parameter declaration as in this example:
+
+```
+FUNCTION plusOne(ByRef a As Ubyte) As UByte
+  LET a = a + 1
+  RETURN a
+END FUNCTION
+
+LET a = 0
+PRINT plusOne(a): REM prints 1
+PRINT a: REM prints 1; original value of A has been *modified* within the function
+```
+ 
+Here the variable `a` is being modified within the function, and this modification persist upon return.
+Except for arrays, when `ByRef` or [ByVAL](byval.md) is not specified in [FUNCTION](function.md) or [SUB](sub.md)
+parameters, [ByVAL](byval.md) will be used by default. On the other hand, if the parameter is an array,
+and no access is specified, it's supposed to be `ByRef` (arrays cannot be passed by value).
+
+ByRef allows us to pass arrays to [FUNCTION](function.md) or [SUB](sub.md):
+
+```
+REM arrays passed to functions can be of *any dimensions*. Use LBOUND and UBOUND to detect dimensions!
+FUNCTION maxValue(ByRef a() as Ubyte) As UByte
+  DIM i as UInteger
+  DIM result As UByte = 0 
+  FOR i = 0 TO 4
+    IF a(i) > result THEN result = a(i)
+  NEXT i
+  RETURN result
+END FUNCTION
+
+DIM myArray(4) As UByte = {4, 3, 1, 2, 5}
+PRINT "Max value is "; maxValue(myArray)
+```
+
+In this example, is `ByRef` was omitted, it will be used by default, since the parameter was an array.
+Arrays cannot be passed [ByVAL](byval.md).
+
+`ByRef` is also useful to return values in the parameters. [RETURN](return.md) allows to return a single value
+from a [FUNCTION](function.md), but we can return several values by storing the result in those parameters.
+
+`ByRef` requires the parameter to be an _lvalue_, that is, a variable, an array or an array cell. You cannot use
+`ByRef` with expressions (i.e. numbers) because you cannot store a value in them.
+
+Example of wrong usage:
+
+```
+FUNCTION plusOne(ByRef a As Ubyte) As UByte
+  LET a = a + 1
+  RETURN a
+END FUNCTION
+
+
+DIM i as UByte = 7
+DIM myArray(5) as Ubyte
+
+PRINT plusOne(5): REM syntax error, 5 is not a variable or an array element.
+PRINT plusOne(i): REM Ok. Will change i value to 8, and print 8)
+PRINT plusOne(i + 1): REM syntax error, i + 1 is not a variable
+PRINT plusOne(myArray(3)): REM Ok. Will increase myArray(3) by 1 and print the result
+```
+
+See also:
+
+* [FUNCTION](function.md)
+* [RETURN](return.md)
+* [SUB](sub.md)
+* [ByVAL](byval.md)

docs/byval.md

@@ -0,0 +1,30 @@
+#ByVAL
+
+`ByVal` is a modifier used in function parameters to specify that the parameters is passed by value (that is, 
+a copy of the value is passed to the [FUNCTION](function.md) or [SUB](sub.md)).
+
+##Syntax
+
+It's used in function parameter declaration as in this example:
+
+```
+FUNCTION plusOne(ByVal a As Ubyte) As UByte
+  LET a = a + 1
+  RETURN a
+END FUNCTION
+
+LET a = 0
+PRINT plusOne(a): REM prints 1
+PRINT a: REM prints 0; original value of A is preserved
+```
+ 
+Here the variable `a` is being modified within the function, but the original value is preserved upon return.
+Except for arrays, when [ByREF](byref.md) or `ByVal` is not specified in [FUNCTION](function.md) or [SUB](sub.md)
+parameters, `ByVal` will be used by default. On the other hand, if the parameter is an array, and no access is 
+specified, it's supposed to be [ByREF](byref.md) (arrays cannot be passed by value).
+
+See also:
+
+* [FUNCTION](function.md)
+* [SUB](sub.md)
+* [ByREF](byref.md)

docs/function.md

@@ -73,3 +73,12 @@ END FUNCTION
 If you invoke zxbasic using `-O1` (or higher) optimization flag the compiler will detect and ignore unused functions
 (thus saving memory space). It will also issue a warning (perhaps you forgot to call it?),
 that can be ignored.
+
+##See Also
+
+* [SUB](sub.md)
+* [ASM](asm.md)
+* [END](end.md)
+* [RETURN](return.md)
+* [ByREF](byref.md)
+* [ByVAL](byval.md)