diff --git a/spec.md b/spec.md
index c1dfaed..8f7ae82 100644
--- a/spec.md
+++ b/spec.md
@@ -1,7 +1,7 @@
 ## Arithmetic
 ```
 1.2 * 4 + 1
-(* result: 5.8 *)
+# result: 5.8 
 ```
 
 ## Few types to learn
@@ -21,7 +21,7 @@ Advanced (uncommon) types:
 ## Functions
 ```
 def msg(username: List[Char]) : List[Char] {
-  "Hello, " ++ username ++ "!"   (* last expr is returned *)
+  "Hello, " ++ username ++ "!"   # last expr is returned
 }
 
 def main() {
@@ -33,7 +33,7 @@ main()
 ## Simple, forward type-inference
 ```
 def zero ()  : Flt32 {
-  3.1       (* error: got Num, but expected F32 *)
+  3.1       # error: got Num, but expected F32
 }
 ```
 
@@ -46,8 +46,8 @@ let passw = "1234"
 ## Mutability only via `ref`
 ```
 let value = Cell.from(1)
-print(Num.to_str(!value))     (* !cell "observes" the cell *)
-value := 2                    (* `:=` mutates the cell *)
+print(Num.to_str(!value))     # !cell "observes" the cell
+value := 2                    # `:=` mutates the cell
 print(Num.to_str(!value))
 ```
 
@@ -66,7 +66,7 @@ all operators:
 
 ## non-nominal struct types
 ```
-(* `type` creates a non-distinct type alias *)
+# `type` creates a non-distinct type alias
 type User = { name: List[Char] }
 type DbUser = { name: List[Char], pass: List[Char] }
 
@@ -80,54 +80,55 @@ def example2() : {name: List[Char], pass: List[Char]} {
 }
 
 def example3() : User {
-  example2()   (* {name:.., pass:...} can automatically decay to {name:...} *)
+  example2()     # {name:.., pass:...} can automatically decay to {name:...}
 }
 ```
 
 ## mixed-tagged union types
 ```
 type Option[t] =
-  'Err Unit   (* Unit that has tag enum 'Err *)
-| t           (* has no tag *)
+  'Err Unit   # Unit that has tag enum 'Err
+| t           # has no tag
 
-(* the tags of unions are weakly attached to the types, but won't decay unless they have to *)
+# the tags of unions are weakly attached to the types, but won't decay unless they have to *)
 def example(n: Num) : Num {
-  let x = 'MyTag n  (* type of x is 'MyTag Num *)
-  x    (* tag gets removed because target type is Num *)
+  let x = 'MyTag n  # type of x is 'MyTag Num
+  x                 # tag gets removed because target type is Num
 }
 
 def example2(n: Num) : Option[Num] {
-  n   (* this works, because the `t` is not tagged in option *)
+  n    # this works, because the `t` is not tagged in option
 }
 
 def example3-invalid() : Option[Num] {
-  Unit  (* error: can't convert type `Unit` into type `'Err Unit | t`
-         *        Either label the expression with 'Err,
-         *        or change the return type to Option[Unit] *)
+  Unit   # error: can't convert type `Unit` into type `'Err Unit | t`
+         #        Either label the expression with 'Err,
+         #        or change the return type to Option[Unit]
 }
 
 def exampe4(): Option[Num] {
   'Err Unit
-  (* type of this expression is: `'Err Unit` *)
-  (* enums can automatically cast, if all the cases from the source enum also exists in the target enum,
-   * which they do here: `'Err Unit` is a case in `'Err Unit | Num` *)
+  # type of this expression is: `'Err Unit`
+  # enums can automatically cast, if all the cases from the source enum also exists in the target enum,
+  # which they do here: `'Err Unit` is a case in `'Err Unit | Num`
 }
 
 def example5-error(): Option[Num] {
   let x = ( 'Err Unit ) :: Option[Unit]
   x
-  (* error: can't convert type `'Err Unit | Unit` into type `'Err Unit | Num`
-   *        The case `Unit` does not exist in the target `'Err Unit | Num` *)
+  # error: can't convert type `'Err Unit | Unit` into type `'Err Unit | Num`
+  #        The case `Unit` does not exist in the target `'Err Unit | Num`
 }
 
 def example6-error(): Option[Unit] {
   let x = 'Error Unit
   x
-  (* in this case, the enum tag does not decay, like in `example`,
-   * because we are casting to an enum *)
-  (* error: can't convert type `'Error Unit` into type `'Err Unit | Num``
-   *        1st possible solution: manually cast to just `Unit` (via `expr :: Unit`), so that it can convert to the second case of the target
-   *        2nd possible solution: pattern match against the enum, to rename the tag from 'Error to 'Err *)
+  # in this case, the enum tag does not decay, like in `example`,
+  # because we are casting to an enum
+
+  # error: can't convert type `'Error Unit` into type `'Err Unit | Num``
+  #        1st possible solution: manually cast to just `Unit` (via `expr :: Unit`), so that it can convert to the second case of the target
+  #        2nd possible solution: pattern match against the enum, to rename the tag from 'Error to 'Err
 }
 ```
 
@@ -136,11 +137,11 @@ def example6-error(): Option[Unit] {
 type Option[t] = 'None | 'Some t
 
 def [t] Match.`a++b`(
-  (* matching against this value *)
+  # matching against this value
   value: List[t],
-  (* left hand side of operator *)
+  # left hand side of operator
   l: List[t],
-  (* right hand side of operator *)
+  # right hand side of operator
   r: MatchUtil.Var[List[t]]
 ) -> Option[{ r: List[t] }] {
   match List.remove_prefix(l, 'from value) {