General content update (#35)

- Updated favicon to remove circle, enlarge text, C is blue, 3 is purple
- Updated landing page for the docs to try to convey a bit more of the project's goals and visually pop
- Updated arrays to add multi-dimensional fixed arrays, placed near the bottom as not key, but still helpful
- Updated optionals page to add linking to the advanced optionals page and introduce the content on each page
- Updated types page to improve the Enum, Optional and Result and some other minor things

src/content/docs/guide/index.mdx

@@ -5,25 +5,40 @@ sidebar:
   order: 1
 ---
 
-Hello, the C3 Guide is a guide to the C3 Programming Language. It is a work in progress, and will be continually updated.
-
 ## What is C3?
 
-C3 is a system programming language based on C. It is an evolution of C enabling the same paradigms and 
-retaining the same syntax as far as possible.
+C3 is an evolution of C and a systems programming language, featuring:
+
+### 🦺 Ergonomics **and** Safety
+- Optionals to safely and quickly handle errors and null.
+- Defer to clean up resources.
+- Slices and foreach for safe iteration.
+- Contracts in comments, to add constraints to your code. 
+
+### ⚡ Performance **by** default
+- Write SIMD vectors to program the hardware directly.
+- Access to different memory allocators to fine tune performance.
+- Zero overhead errors.
+- Fast compilation times.
+- LLVM backend for industrial strength optimisations.
+- Easy to use inline assembly.
+
+### 🔋Batteries **included** standard library
+- Dynamic containers and strings.
+- Cross-platform abstractions for ease of use.
+- Access to the native platform when you need it.
 
-## Features
+### 🔧 Leverage **existing** C or C++ libraries
+- Full C ABI compatibility.
+- C3 can link C code, C can link C3 code.
 
-- Full C ABI compatibility  
-- Module system 
-- Generic modules
-- Design by contract
-- Zero overhead errors
-- Semantic macro system
-- First-class SIMD vector types
-- Struct subtyping
-- Safe array access using slices
-- Easy to use inline assembly
-- Cross-platform standard library which includes dynamic containers and strings
-- LLVM backend
+### 📦 Modules **are** the future
+- Modules namespace code.
+- Modules make encapsulation simple with explicit control.
+- Interfaces define shared behaviour to write robust libraries.
+- Generic modules make extending code easier.
+- Simple struct composition and reuse with struct subtyping.
 
+### 🎓 Macros **without** a PhD
+- Macros can be similar to normal functions.
+- Or write code that understands the types in your code.

src/content/docs/references/docs/arrays.md

@@ -8,7 +8,7 @@ sidebar:
 Arrays have a central role in programming. C3 offers built-in arrays, slices and [vectors](/references/docs/vectors/).
 The standard library enhances this further with dynamically sized arrays and other collections.
 
-## Fixed arrays
+## Fixed size 1D arrays
 
 These are declared as `<type>[<size>]`, e.g. `int[4]`. Fixed arrays are treated as values and will be copied if given as parameter. Unlike C, the number is part of its type. Taking a pointer to a fixed array will create a pointer to a fixed array, e.g. `int[4]*`. 
 
@@ -33,6 +33,7 @@ When you want to initialize a fixed array without specifying the size, use the [
 int[3] a = { 1, 2, 3 };
 int[*] b = { 4, 5, 6 }; // Type inferred to be int[3]
 ```
+
 ## Slice
 
 The final type is the slice `<type>[]`  e.g. `int[]`. A slice is a view into either a fixed or variable array. Internally it is represented as a struct containing a pointer and a size. Both fixed and variable arrays may be converted into slices, and slices may be implicitly converted to pointers.
@@ -281,3 +282,58 @@ fn void test()
 }
 ```
 
+## Fixed size multi-dimensional arrays
+
+To declare two dimensional fixed arrays as `<type>[<x-size>, <y-size>] arr`, like `int[4][2] arr`. Below you can see how this compares to C:
+```c
+// C 
+// Uses: name[<rows>][<columns>]
+int array_in_c[4][2] = {
+    {1, 2},
+    {3, 4},
+    {5, 6},
+    {7, 8},
+};
+
+// C3
+// Uses: <type>[<x-size>][<y-size>]
+// C3 declares the dimensions, inner-most to outer-most
+int[4][2] array = {
+    {1, 2, 3, 4},
+    {5, 6, 7, 8},
+};
+
+// To match C we must invert the order of the dimensions 
+int[2][4] array = {
+    {1, 2},
+    {3, 4},
+    {5, 6},
+    {7, 8},
+};
+
+// C3 also supports Irregular arrays, for example:
+int[][4] array = {
+    { 1 },
+    { 2, 3 },
+    { 4, 5, 6 },
+    { 7, 8, 9, 10 },
+};
+```
+
+:::note
+Accessing the multi-dimensional fixed array has inverted array index order to when the array was declared.
+```c3
+// Uses: <type>[<x-size>][<y-size>]
+int[2][4] array = {
+    {1, 2},
+    {3, 4},
+    {5, 6},
+    {7, 8},
+};
+
+// Access fixed array using: array[<row>][<column>]
+int value = array[3][1]; // 8
+```
+:::
+
+

src/content/docs/references/docs/examples.md

@@ -565,7 +565,11 @@ macro long @fib(long $n)
 const long FIB19 = @fib(19); 
 // Same as const long FIB19 = 4181;
 ```
+:::note
+C3 macros are designed to provide a replacement for C preprocessor macros. They extend such macros by providing compile time evaluation using constant folding, which offers an IDE friendly, limited, compile time execution.
 
+However, if you are doing more complex compile time code generation it is recommended to use `$exec` and related techniques to generate code in external scripts instead.
+:::
 Read more about compile time execution [here](/references/docs/compiletime).
 
 #### Generic modules

src/content/docs/references/docs/generics.md

@@ -9,14 +9,14 @@ Generic modules are parameterized modules that allow functionality for arbitrary
 
 For generic modules, the generic parameters follows the module name:
 
-```
+```c3
 // TypeA, TypeB, TypeC are generic parameters.
 module vector(<TypeA, TypeB, TypeC>);
 ```
 
 Code inside a generic module may use the generic parameters as if they were well-defined symbols:
 
-```
+```c3
 module foo_test(<Type1, Type2>);
 
 struct Foo 
@@ -32,7 +32,7 @@ fn Type2 test(Type2 b, Foo *foo)
 
 Including a generic module works as usual:
 
-```
+```c3
 import foo_test;
 
 def FooFloat = Foo(<float, double>);
@@ -51,7 +51,7 @@ foo_test::test(<int, double>)(1.0, &g);
 
 Just like for macros, optional constraints may be added to improve compile errors:
 
-```
+```c3
 /**
  * @require $assignable(1, TypeB) && $assignable(1, TypeC)
  * @require $assignable((TypeB)1, TypeA) && $assignable((TypeC)1, TypeA)
@@ -61,7 +61,7 @@ module vector(<TypeA, TypeB, TypeC>);
 /* .. code * ../
 ```
 
-```
+```c3
 def testFunction = vector::testFunc(<Bar, float, int>);
 
 // This would give the error 

src/content/docs/references/docs/optionals.md

@@ -5,6 +5,12 @@ sidebar:
     order: 114
 ---
 
+In this section we will go over the *essential* information about Optionals and safe methods for working with them, for example 
+ [`if (catch optional_value)`](#checking-if-an-optional-is-empty) 
+ and the [Rethrow operator `!`](#using-the-rethrow-operator--to-unwrap-an-optional-value).
+
+In the [advanced section](../optionals_advanced/) there are other *nice to have* features. Like an alternative to safely unwrap a result from an Optionals using [`if (try optional_value)`](../optionals_advanced/#run-code-if-the-optional-has-a-result) and an unsafe method to [force unwrap `!!`](../optionals_advanced/#force-unwrapping-expressions) a result from an Optional, return [default values for optionals `??`](../optionals_advanced/#return-a-default-value-if-optional-is-empty) if they are empty and other more specialised concepts.
+
 ## What is an Optional? 
 
 Optionals are a safer alternative to returning `-1` or `null` from 
@@ -30,8 +36,7 @@ int! b = IoError.FILE_NOT_FOUND?;
 Unwrapping an Optional is safe because it checks it has a 
 result present before trying to use it.
 
-After unwrapping a variable is a non-Optional, and behaves 
-like a normal variable.
+After unwrapping, the variable then behaves like a normal variable, a non-Optional.
 :::
 
 ## Checking if an Optional is empty