Update, correct, and expand documentation

docs/pattern-matching.md

@@ -88,19 +88,23 @@ To ensure that recursive pattern matching functions don't loop in strict mode, i
 ```py
 # This is what the Foo function actually compiles to.
 # With -Olinearize-matches and -Ofloat-combinators (default on strict mode)
+# Main function
 (Foo) = λa λb λc (switch a { 0: Foo__C8; _: Foo__C9; } b c)
 
-(Foo__C5) = λa switch a { 0: λ* Baz; _: Foo__C4; }    # Foo.case_0
-(Foo__C4) = λ* λa (a Foo__C3)                         # Foo.case_0.case_false
-(Foo__C3) = λa switch a { 0: Baz; _: Foo__C2; }       # Part of cons pattern matching
-(Foo__C2) = λ* λa λb (b Foo__C1 a)                    # Foo.case_0.case_false.case_cons
-(Foo__C1) = λa switch a { 0: λ* Baz; _: Foo__C0; }    # Part of cons pattern matching
-(Foo__C0) = λ* λa λb λc (Bar c a b)                   # Foo.case_0.case_false.case_cons.case_cons
+# Case 0 branch
+(Foo__C8) = λa λb (a Foo__C5 b)                       # Foo.case_0.route
+(Foo__C5) = λa switch a { 0: λ* Baz; _: Foo__C4; }    # Foo.case_0.bool_true
+(Foo__C4) = λ* λa (a Foo__C3)                         # Foo.case_0.bool_false
+(Foo__C3) = λa switch a { 0: Baz; _: Foo__C2; }       # Foo.case_0.bool_false.case_cons1
+(Foo__C2) = λ* λa λb (b Foo__C1 a)                    # Foo.case_0.bool_false.case_cons1.handle
+(Foo__C1) = λa switch a { 0: λ* Baz; _: Foo__C0; }    # Foo.case_0.bool_false.case_cons2
+(Foo__C0) = λ* λa λb λc (Bar c a b)                   # Foo.case_0.bool_false.case_cons2.case_nil
 
-(Foo__C6) = λ* λ* λa (+ a 1)                          # Foo.case_+.case_false
-(Foo__C7) = λa switch a { 0: λ* λ* 0; _: Foo__C6; }   # Part of bool pattern matching
+# Case non-zero branch
 (Foo__C9) = λa λb λc (b Foo__C7 c a)                  # Foo.case_+
-(Foo__C8) = λa λb (a Foo__C5 b)                       # Part of main pattern matching
+(Foo__C7) = λa switch a { 0: λ* λ* 0; _: Foo__C6; }   # Foo.case_+.case_check
+(Foo__C6) = λ* λ* λa (+ a 1)                          # Foo.case_+.case_false
+
 # As an user, you can't write a function with __ on its name, that sequence is reserved for things generated by the compiler.
 ```
 

src/fun/builtins.bend

@@ -84,13 +84,13 @@ String/split.go (cs: String) (delim: u24) (acc: (List String)) : (List String)
 String/split.go (String/Nil) _ acc = (List/reverse acc)
 String/split.go (String/Cons c cs) delim acc =
   if (== c delim) {
-#{ Start a new split string #}
+  # Start a new split string.
     (String/split.go cs delim (List/Cons String/Nil acc))
   } else {
     match acc {
-#{ Add the current character to the current split string #}
+  # Add the current character to the current split string.
       List/Cons: (String/split.go cs delim (List/Cons (String/Cons c acc.head) acc.tail))
-#{ Should be unreachable #}
+  # Should be unreachable.
       List/Nil: []
     }
   }
@@ -385,7 +385,16 @@ def IO/sleep(seconds: f24) -> IO(None):
 
 ### File IO primitives
 
-#{ Opens a file with with `path` being given as a string and `mode` being a string with the mode to open the file in. The mode should be one of the following: #}
+#{ 
+  Opens a file with with `path` being given as a string and `mode` being a string with the mode to open the file in. 
+  The mode should be one of the following: 
+  "r": Read mode
+  "w": Write mode (write at the beginning of the file, overwriting any existing content)
+  "a": Append mode (write at the end of the file)
+  "r+": Read and write mode
+  "w+": Read and write mode
+  "a+": Read and append mode
+#}
 def IO/FS/open(path: String, mode: String) -> IO(Result(u24, u24)):
   return IO/unwrap_inner(IO/call("OPEN", (path, mode)))
 
@@ -786,13 +795,11 @@ String/encode_ascii (String/Nil)       = (List/Nil)
 
 # Math
 
-#{
-  Math/PI() -> f24
-  The Pi (π) constant.
-#}
+#{ The Pi (π) constant.#}
 def Math/PI() -> f24:
   return 3.1415926535
 
+#{ Euler's number #}
 def Math/E() -> f24:
   return 2.718281828