Changes

src/SUMMARY.md

@@ -36,4 +36,4 @@
 # Release History
 - ["Vela" 0.x.x](vela.md)
   - [0.1.0](vela_0.1.0.md)
-- ["Fornax" 1.x.x](fornax.md)
+- ["Fornax" 1.x.x (Next Release)](fornax.md)

src/functions.md

@@ -1 +1,80 @@
 # Functions
+
+## Defining Functions
+
+In Solstice, functions are a way to organise and reuse code. Here's an example function:
+
+```solstice
+def add(int a, int b) int {
+    return a + b
+}
+```
+
+Here's what each part is:
+
+* `def`: Means "define". Tells Solstice we are defining a function.
+* `add`: This is your function name! Choose something unique.
+* `(int a, int b)`: These are the arguments your function takes.
+  * Enclose your argument type and name pairs in brackets.
+  * The first identifier should be a type (such as `int`, `string`, etc), the second should be an identifer
+  * After each type-name pair, add a comma unless you've got no more arguments to define
+* `int`: This is your return type
+* `return a + b`: This is where your code goes for the function
+
+## Calling Functions
+
+Call a function in Solstice like this:
+
+```solstice
+myFunction(a, b, c)
+```
+
+where:
+
+* `myFunction` is the name of your function
+* `(a, b, c)` are the arguments you would like to pass to the function.
+  * Enclose the arguments in parentheses (`( )`)
+  * Each argument should be seperated by a comma
+  * Solstice will type-check each argument to ensure it matches the function's specified types
+
+## Closures and Scoping
+
+Each function has an attached closure, which is the state captured at runtime when the function is defined. All variables in the closure can be accessed inside the function body, however the closure cannot be modified (meaning all variables captured remain consistent across function runs).
+
+This behaviour ensures that functions are not affected by global state, and will always have reliable, consistent behaviour.
+
+Additionally, all defined arguments are avaliable in scope.
+
+```solstice
+x = 10
+
+def myFunction() int {
+    // Here, x is avaliable, however if we modify it,
+    // our changes won't affect the external state, or
+    // the state of this function when it runs.
+    puts x
+    x = 5
+    return x
+}
+
+myFunction() // returns 5, prints 10
+myFunction() // returns 5, prints 10
+
+puts x // prints 10, x has not been modified by myFunction
+```
+
+## The type of a function
+
+If you'd like to accept a function as an argument, you need to specify it's type signature. That can be done like this:
+
+```solstice
+fun(int, string) bool
+```
+
+where:
+
+* `fun` tells Solstice we're writing a type signature for a function
+* `(int, string)` is the list of argument types (names are not needed), seperated by commas, surrounded by brackets
+* `bool` is the return type
+
+making this type represent a function which takes an `int` and a `string`, and returns a `bool`.

src/introduction.md

@@ -4,4 +4,6 @@ Welcome to the Solstice documentation! Here we have a tutorial (starting [here](
 
 If you're new to Solstice, I'd recommend starting the tutorial, at the [installation](installation.md) page. If you've already installed Solstice, start at the [Basics](basics.md) page.
 
+Found a mistake? Report it at [https://chookspace.com/solstice/docs](https://chookspace.com/solstice/docs)
+
 Docs generated by mdBook.

src/reserved_words.md

@@ -24,4 +24,8 @@ new
 as
 sizeof
 pragma
+
+fun
+template
+object
 ```

src/tutorial_variables.md

@@ -19,7 +19,7 @@ where:
   * a character (a single letter)
   * a boolean (either `true` or `false`)
 
-We'll look at types of values in the next part.
+We'll look at types of values soon.
 
 ## Recalling Variables