doc update

Author: robertmuth

FE/Docs/README.md

@@ -1,13 +1,17 @@
 ## Frontend
 
-[Overview](tutorial.md)
+[Language Overview](tutorial.md)
 
 [AST Node Description](ast.md)
 
 [Macro System](macros.md)
 
 [Type System](types.md)
 
+[Union Types](union_types.md)
+
 [Casting](casting.md)
 
+[Polymorphism](polymorphism.md)
+
 [Codegen For Conditional Expressions](codegen_for_cond_exprs.md)

FE/Docs/historical.md

@@ -1,24 +1,5 @@
-# Cwerg Language
+# Design Choices
 
-Cwerg tries to find the right balance between language expressiveness and compiler implementation complexity.
-The hope is to reach a sweet spot *above* what C gives us today and make it convenient to write
-system software like operating systems and compilers in this language.
-
-
-Warning: This is still quite experimental. We expexct to gain some
-more insights about the design-space by bootstrapping the front- and backend.
-
-### Philosophy
-
-Above all Cwerg is meant to be a **small** language. Since small is subjective we have
-set a complexity budget for about 10kLOC for a compiler frontend with basic optimizations.
-
-All control flow and all memory allocation is explicit.
-
-Discouraged practices are possible but require explicit overrides, e.g.:
-uninitialized variables, global visibility, mutability, unchecked array accesses,
-untagged unions, ...
-...
 
 ## Syntax
 
@@ -30,25 +11,9 @@ Comments wil be explicit in the AST and cannot occur in arbitrary places.
 Similarly, parenthesis used to group expression will be modelled in the AST.
 
 * [List of S-Expression Nodes](../FrontEndDocs/ast.md)
-* [Macros](../FrontEndDocs/macros.md)
-* [Casting](../FrontEndDocs/casting.md)
-
-
-## Code Examples (using S-Expr Syntax)
 
-* [Print Argv](TestData/print_argv.cw)
-* [Heap Sort](TestData/heapsort.cw)
-* [Fizzbuzz](TestData/fizzbuzz.cw)
-* [Sieve](TestData/sieve.cw)
-* [Word Count](TestData/wordcount.cw)
 
-## Code Examples (using Concrete Syntax)
 
-* [Print Argv](ConcreteSyntax/TestData/print_argv.cw)
-* [Fizzbuzz](ConcreteSyntax/TestData/fizzbuzz.cw)
-* [Sieve](ConcreteSyntax/TestData/sieve.cw)
-* [Word Count](ConcreteSyntax/TestData/wordcount.cw)
-*
 ## Features Relative to C
 
 Added

FE/Docs/polymorphism.md

@@ -0,0 +1,67 @@
+# Polymorphism
+
+Besides parameterized modules, Cwerg supports a limited form of (ad-hoc) polymorphism for functions.
+There is no dynamic dispatch as everything is resolved at compile-time.
+
+Example:
+```
+fun SysRender@(v u8, out span!(u8)) uint:
+    return FmtDecU8(v, out)
+```
+
+**Note the trailing "@" which indicates that a function is polymorphic.**
+
+This example has two effects:
+
+1. It defines a function that render an `u8` value in decimal into the buffer `out` and returns the number of characters written.
+2. It registers a family of functions named `SysRender@` that only differ in their first argument.
+
+
+
+Functions can be added to this family by re-using the name  like so
+```
+fun SysRender@(v u32, out span!(u8)) uint:
+    return FmtDecU32(v, out)
+```
+
+Note, this function has a different first parameter type for the first argument while the other stay the same.
+**Cwerg's polymorphism applieds to the first argument only!**
+
+Printing in hex instead of decimal could be accomplished like so:
+
+```
+pub wrapped type u32_hex = u32
+
+fun SysRender@(v u32_hex, out span!(u8)) uint:
+    return FmtHexU32(unwrap(v), out)
+```
+
+Assuming the functions above are defined in a module named `fmt` they can be called like so:
+```
+    ...
+    ref let! buf_raw = [1024]u8{}
+    let! buf span!(u8) = buf_raw
+    set buf = IncSpan(buf, fmt::SysRender@(666_u32, buf))
+    set buf = IncSpan(buf, fmt::SysRender@(66_u8, buf))
+    set buf = IncSpan(buf, fmt::SysRender@(
+        wrap_as(666,  fmt:: u32_hex), buf))
+    ...
+```
+
+Defining SysRender@ for a data type in another module can be accomplished like so:
+```
+rec Point:
+    x u32
+    y u32
+
+fun fmt::SysRender@(v Point, out span!(u8)) uint:
+    let! buf = out
+    set buf = IncSpan(buf, fmt::SysRender@(v.x, buf))
+    set buf = IncSpan(buf, fmt::SysRender@(", ", buf))
+    set buf = IncSpan(buf, fmt::SysRender@(v.y, buf))
+    return len(out) - len(buf)
+
+```
+
+Note, that the definition uses a `qualified` name referencing the family of
+polymorphic function we want to add to.

FE/Docs/tutorial.md

@@ -564,6 +564,8 @@ Functions can only have one result.
 
 Function parameters are not mutable.
 
+Polymorphism is described [here](polymorphism.md)
+
 ### Enums, Types (Typedefs) and Recs (Structs)
 
 These were covered in the Type Section above