Yet more renamings.

17 files changed, 355 insertions, 246 deletions

diff --git a/stdlib/source/library/lux/data/binary.lux b/stdlib/source/library/lux/data/binary.lux
index 6cd8c722b..deec60d53 100644
--- a/stdlib/source/library/lux/data/binary.lux
+++ b/stdlib/source/library/lux/data/binary.lux
@@ -33,7 +33,10 @@
    ["Offset" (%.nat offset)]
    ["Length" (%.nat length)]))
 
-(with_expansions [<jvm> (as_is (type: #export Binary (ffi.type [byte]))
+(with_expansions [<documentation> (as_is {#.doc (doc "A binary BLOB of data.")})
+                  <jvm> (as_is (type: #export Binary
+                                 <documentation>
+                                 (ffi.type [byte]))
 
                                (ffi.import: java/lang/Object)
                                
@@ -75,14 +78,17 @@
                   (length ffi.Number)])
                
                (type: #export Binary
+                 <documentation>
                  Uint8Array))
 
         @.python
         (type: #export Binary
+          <documentation>
           (primitive "bytearray"))
 
         @.scheme
         (as_is (type: #export Binary
+                 <documentation>
                  (primitive "bytevector"))
                
                (ffi.import: (make-bytevector [Nat] Binary))
@@ -92,6 +98,7 @@
 
        ## Default
        (type: #export Binary
+         <documentation>
          (array.Array (I64 Any)))))
 
 (template: (!size binary)
@@ -114,167 +121,177 @@
        ## Default
        (array.size binary)))
 
-(template: (!read idx binary)
-  (for {@.old (..i64 (ffi.array_read idx binary))
-        @.jvm (..i64 (ffi.array_read idx binary))
+(template: (!read index binary)
+  (for {@.old (..i64 (ffi.array_read index binary))
+        @.jvm (..i64 (ffi.array_read index binary))
 
         @.js
         (|> binary
             (: ..Binary)
             (:as (array.Array .Frac))
-            ("js array read" idx)
+            ("js array read" index)
             f.nat
             .i64)
 
         @.python
         (|> binary
             (:as (array.Array .I64))
-            ("python array read" idx))
+            ("python array read" index))
 
         @.scheme
-        (..bytevector-u8-ref [binary idx])}
+        (..bytevector-u8-ref [binary index])}
 
        ## Default
        (|> binary
-           (array.read idx)
+           (array.read index)
            (maybe.else (: (I64 Any) 0))
            (:as I64))))
 
-(template: (!!write <byte_type> <post> <write> idx value binary)
+(template: (!!write <byte_type> <post> <write> index value binary)
   (|> binary
       (: ..Binary)
       (:as (array.Array <byte_type>))
-      (<write> idx (|> value .nat (n.% (hex "100")) <post>))
+      (<write> index (|> value .nat (n.% (hex "100")) <post>))
       (:as ..Binary)))
 
-(template: (!write idx value binary)
-  (for {@.old (ffi.array_write idx (..byte value) binary)
-        @.jvm (ffi.array_write idx (..byte value) binary)
+(template: (!write index value binary)
+  (for {@.old (ffi.array_write index (..byte value) binary)
+        @.jvm (ffi.array_write index (..byte value) binary)
 
-        @.js (!!write .Frac n.frac "js array write" idx value binary)
-        @.python (!!write (I64 Any) (:as (I64 Any)) "python array write" idx value binary)
-        @.scheme (exec (..bytevector-u8-set! [binary idx value])
+        @.js (!!write .Frac n.frac "js array write" index value binary)
+        @.python (!!write (I64 Any) (:as (I64 Any)) "python array write" index value binary)
+        @.scheme (exec (..bytevector-u8-set! [binary index value])
                    binary)}
 
        ## Default
-       (array.write! idx (|> value .nat (n.% (hex "100"))) binary)))
+       (array.write! index (|> value .nat (n.% (hex "100"))) binary)))
 
 (def: #export size
   (-> Binary Nat)
   (|>> !size))
 
-(def: #export create
+(def: #export (create size)
+  {#.doc (doc "A fresh/empty binary BLOB of the specified size.")}
   (-> Nat Binary)
-  (for {@.old (|>> (ffi.array byte))
-        @.jvm (|>> (ffi.array byte))
+  (for {@.old (ffi.array byte size)
+        @.jvm (ffi.array byte size)
 
         @.js
-        (|>> n.frac ArrayBuffer::new Uint8Array::new)
+        (|> size n.frac ArrayBuffer::new Uint8Array::new)
 
         @.python
-        (|>> ("python apply" (:as ffi.Function ("python constant" "bytearray")))
-             (:as Binary))
+        (|> size
+            ("python apply" (:as ffi.Function ("python constant" "bytearray")))
+            (:as Binary))
 
         @.scheme
-        (|>> ..make-bytevector)}
+        (..make-bytevector size)}
 
        ## Default
-       array.new))
+       (array.new size)))
 
 (def: #export (fold f init binary)
   (All [a] (-> (-> I64 a a) a Binary a))
   (let [size (..!size binary)]
-    (loop [idx 0
+    (loop [index 0
            output init]
-      (if (n.< size idx)
-        (recur (inc idx) (f (!read idx binary) output))
+      (if (n.< size index)
+        (recur (inc index) (f (!read index binary) output))
         output))))
 
-(def: #export (read/8 idx binary)
+(def: #export (read/8 index binary)
+  {#.doc (doc "Read 1 byte (8 bits) at the given index.")}
   (-> Nat Binary (Try I64))
-  (if (n.< (..!size binary) idx)
-    (#try.Success (!read idx binary))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
+  (if (n.< (..!size binary) index)
+    (#try.Success (!read index binary))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
 
-(def: #export (read/16 idx binary)
+(def: #export (read/16 index binary)
+  {#.doc (doc "Read 2 bytes (16 bits) at the given index.")}
   (-> Nat Binary (Try I64))
-  (if (n.< (..!size binary) (n.+ 1 idx))
+  (if (n.< (..!size binary) (n.+ 1 index))
     (#try.Success ($_ i64.or
-                      (i64.left_shifted 8 (!read idx binary))
-                      (!read (n.+ 1 idx) binary)))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
+                      (i64.left_shifted 8 (!read index binary))
+                      (!read (n.+ 1 index) binary)))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
 
-(def: #export (read/32 idx binary)
+(def: #export (read/32 index binary)
+  {#.doc (doc "Read 4 bytes (32 bits) at the given index.")}
   (-> Nat Binary (Try I64))
-  (if (n.< (..!size binary) (n.+ 3 idx))
+  (if (n.< (..!size binary) (n.+ 3 index))
     (#try.Success ($_ i64.or
-                      (i64.left_shifted 24 (!read idx binary))
-                      (i64.left_shifted 16 (!read (n.+ 1 idx) binary))
-                      (i64.left_shifted 8 (!read (n.+ 2 idx) binary))
-                      (!read (n.+ 3 idx) binary)))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
-
-(def: #export (read/64 idx binary)
+                      (i64.left_shifted 24 (!read index binary))
+                      (i64.left_shifted 16 (!read (n.+ 1 index) binary))
+                      (i64.left_shifted 8 (!read (n.+ 2 index) binary))
+                      (!read (n.+ 3 index) binary)))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
+
+(def: #export (read/64 index binary)
+  {#.doc (doc "Read 8 bytes (64 bits) at the given index.")}
   (-> Nat Binary (Try I64))
-  (if (n.< (..!size binary) (n.+ 7 idx))
+  (if (n.< (..!size binary) (n.+ 7 index))
     (#try.Success ($_ i64.or
-                      (i64.left_shifted 56 (!read idx binary))
-                      (i64.left_shifted 48 (!read (n.+ 1 idx) binary))
-                      (i64.left_shifted 40 (!read (n.+ 2 idx) binary))
-                      (i64.left_shifted 32 (!read (n.+ 3 idx) binary))
-                      (i64.left_shifted 24 (!read (n.+ 4 idx) binary))
-                      (i64.left_shifted 16 (!read (n.+ 5 idx) binary))
-                      (i64.left_shifted 8 (!read (n.+ 6 idx) binary))
-                      (!read (n.+ 7 idx) binary)))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
-
-(def: #export (write/8 idx value binary)
+                      (i64.left_shifted 56 (!read index binary))
+                      (i64.left_shifted 48 (!read (n.+ 1 index) binary))
+                      (i64.left_shifted 40 (!read (n.+ 2 index) binary))
+                      (i64.left_shifted 32 (!read (n.+ 3 index) binary))
+                      (i64.left_shifted 24 (!read (n.+ 4 index) binary))
+                      (i64.left_shifted 16 (!read (n.+ 5 index) binary))
+                      (i64.left_shifted 8 (!read (n.+ 6 index) binary))
+                      (!read (n.+ 7 index) binary)))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
+
+(def: #export (write/8 index value binary)
+  {#.doc (doc "Write 1 byte (8 bits) at the given index.")}
   (-> Nat (I64 Any) Binary (Try Binary))
-  (if (n.< (..!size binary) idx)
+  (if (n.< (..!size binary) index)
     (#try.Success (|> binary
-                      (!write idx value)))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
+                      (!write index value)))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
 
-(def: #export (write/16 idx value binary)
+(def: #export (write/16 index value binary)
+  {#.doc (doc "Write 2 bytes (16 bits) at the given index.")}
   (-> Nat (I64 Any) Binary (Try Binary))
-  (if (n.< (..!size binary) (n.+ 1 idx))
+  (if (n.< (..!size binary) (n.+ 1 index))
     (#try.Success (|> binary
-                      (!write idx (i64.right_shifted 8 value))
-                      (!write (n.+ 1 idx) value)))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
+                      (!write index (i64.right_shifted 8 value))
+                      (!write (n.+ 1 index) value)))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
 
-(def: #export (write/32 idx value binary)
+(def: #export (write/32 index value binary)
+  {#.doc (doc "Write 4 bytes (32 bits) at the given index.")}
   (-> Nat (I64 Any) Binary (Try Binary))
-  (if (n.< (..!size binary) (n.+ 3 idx))
+  (if (n.< (..!size binary) (n.+ 3 index))
     (#try.Success (|> binary
-                      (!write idx (i64.right_shifted 24 value))
-                      (!write (n.+ 1 idx) (i64.right_shifted 16 value))
-                      (!write (n.+ 2 idx) (i64.right_shifted 8 value))
-                      (!write (n.+ 3 idx) value)))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
-
-(def: #export (write/64 idx value binary)
+                      (!write index (i64.right_shifted 24 value))
+                      (!write (n.+ 1 index) (i64.right_shifted 16 value))
+                      (!write (n.+ 2 index) (i64.right_shifted 8 value))
+                      (!write (n.+ 3 index) value)))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
+
+(def: #export (write/64 index value binary)
+  {#.doc (doc "Write 8 bytes (64 bits) at the given index.")}
   (-> Nat (I64 Any) Binary (Try Binary))
-  (if (n.< (..!size binary) (n.+ 7 idx))
-    (for {@.scheme (let [write_high (|>> (!write idx (i64.right_shifted 56 value))
-                                         (!write (n.+ 1 idx) (i64.right_shifted 48 value))
-                                         (!write (n.+ 2 idx) (i64.right_shifted 40 value))
-                                         (!write (n.+ 3 idx) (i64.right_shifted 32 value)))
-                         write_low (|>> (!write (n.+ 4 idx) (i64.right_shifted 24 value))
-                                        (!write (n.+ 5 idx) (i64.right_shifted 16 value))
-                                        (!write (n.+ 6 idx) (i64.right_shifted 8 value))
-                                        (!write (n.+ 7 idx) value))]
+  (if (n.< (..!size binary) (n.+ 7 index))
+    (for {@.scheme (let [write_high (|>> (!write index (i64.right_shifted 56 value))
+                                         (!write (n.+ 1 index) (i64.right_shifted 48 value))
+                                         (!write (n.+ 2 index) (i64.right_shifted 40 value))
+                                         (!write (n.+ 3 index) (i64.right_shifted 32 value)))
+                         write_low (|>> (!write (n.+ 4 index) (i64.right_shifted 24 value))
+                                        (!write (n.+ 5 index) (i64.right_shifted 16 value))
+                                        (!write (n.+ 6 index) (i64.right_shifted 8 value))
+                                        (!write (n.+ 7 index) value))]
                      (|> binary write_high write_low #try.Success))}
          (#try.Success (|> binary
-                           (!write idx (i64.right_shifted 56 value))
-                           (!write (n.+ 1 idx) (i64.right_shifted 48 value))
-                           (!write (n.+ 2 idx) (i64.right_shifted 40 value))
-                           (!write (n.+ 3 idx) (i64.right_shifted 32 value))
-                           (!write (n.+ 4 idx) (i64.right_shifted 24 value))
-                           (!write (n.+ 5 idx) (i64.right_shifted 16 value))
-                           (!write (n.+ 6 idx) (i64.right_shifted 8 value))
-                           (!write (n.+ 7 idx) value))))
-    (exception.except ..index_out_of_bounds [(..!size binary) idx])))
+                           (!write index (i64.right_shifted 56 value))
+                           (!write (n.+ 1 index) (i64.right_shifted 48 value))
+                           (!write (n.+ 2 index) (i64.right_shifted 40 value))
+                           (!write (n.+ 3 index) (i64.right_shifted 32 value))
+                           (!write (n.+ 4 index) (i64.right_shifted 24 value))
+                           (!write (n.+ 5 index) (i64.right_shifted 16 value))
+                           (!write (n.+ 6 index) (i64.right_shifted 8 value))
+                           (!write (n.+ 7 index) value))))
+    (exception.except ..index_out_of_bounds [(..!size binary) index])))
 
 (implementation: #export equivalence
   (Equivalence Binary)
@@ -286,11 +303,11 @@
            (let [limit (!size reference)]
              (and (n.= limit
                        (!size sample))
-                  (loop [idx 0]
-                    (if (n.< limit idx)
-                      (and (n.= (!read idx reference)
-                                (!read idx sample))
-                           (recur (inc idx)))
+                  (loop [index 0]
+                    (if (n.< limit index)
+                      (and (n.= (!read index reference)
+                                (!read index sample))
+                           (recur (inc index)))
                       true))))))))
 
 (for {@.old (as_is)
@@ -306,6 +323,7 @@
         ["Target output space" (%.nat target_output)])))
 
 (def: #export (copy bytes source_offset source target_offset target)
+  {#.doc (doc "Mutates the target binary BLOB by copying bytes from the source BLOB to it.")}
   (-> Nat Nat Binary Nat Binary (Try Binary))
   (with_expansions [<jvm> (as_is (do try.monad
                                    [_ (java/lang/System::arraycopy source (.int source_offset) target (.int target_offset) (.int bytes))]
@@ -316,35 +334,37 @@
          ## Default
          (let [source_input (n.- source_offset (!size source))
                target_output (n.- target_offset (!size target))]
-           (if (n.<= source_input bytes)
-             (loop [idx 0]
-               (if (n.< bytes idx)
-                 (exec (!write (n.+ target_offset idx)
-                               (!read (n.+ source_offset idx) source)
+           (if (n.> source_input bytes)
+             (exception.except ..cannot_copy_bytes [bytes source_input target_output])
+             (loop [index 0]
+               (if (n.< bytes index)
+                 (exec (!write (n.+ target_offset index)
+                               (!read (n.+ source_offset index) source)
                                target)
-                   (recur (inc idx)))
-                 (#try.Success target)))
-             (exception.except ..cannot_copy_bytes [bytes source_input target_output]))))))
+                   (recur (inc index)))
+                 (#try.Success target))))))))
 
 (def: #export (slice offset length binary)
+  {#.doc (doc "Yields a subset of the binary BLOB, so long as the specified range is valid.")}
   (-> Nat Nat Binary (Try Binary))
   (let [size (..!size binary)
         limit (n.+ length offset)]
-    (if (n.<= size limit)
+    (if (n.> size limit)
+      (exception.except ..slice_out_of_bounds [size offset length])
       (with_expansions [<jvm> (as_is (#try.Success (java/util/Arrays::copyOfRange binary (.int offset) (.int limit))))]
         (for {@.old <jvm>
               @.jvm <jvm>}
              
              ## Default
-             (..copy length offset binary 0 (..create length))))
-      (exception.except ..slice_out_of_bounds [size offset length]))))
+             (..copy length offset binary 0 (..create length)))))))
 
-(def: #export (drop offset binary)
+(def: #export (drop bytes binary)
+  {#.doc (doc "Yields a binary BLOB with at most the specified number of bytes removed.")}
   (-> Nat Binary Binary)
-  (case offset
+  (case bytes
     0 binary
-    _ (let [distance (n.- offset (..!size binary))]
-        (case (..slice offset distance binary)
+    _ (let [distance (n.- bytes (..!size binary))]
+        (case (..slice bytes distance binary)
           (#try.Success slice)
           slice
           
diff --git a/stdlib/source/library/lux/data/bit.lux b/stdlib/source/library/lux/data/bit.lux
index 05d419b8f..5de3cf526 100644
--- a/stdlib/source/library/lux/data/bit.lux
+++ b/stdlib/source/library/lux/data/bit.lux
@@ -4,7 +4,7 @@
     [abstract
      [monoid (#+ Monoid)]
      [equivalence (#+ Equivalence)]
-     hash
+     [hash (#+ Hash)]
      [codec (#+ Codec)]]
     [control
      ["." function]]]])
diff --git a/stdlib/source/library/lux/data/collection/list.lux b/stdlib/source/library/lux/data/collection/list.lux
index a584f9363..f5d6dcf02 100644
--- a/stdlib/source/library/lux/data/collection/list.lux
+++ b/stdlib/source/library/lux/data/collection/list.lux
@@ -600,7 +600,7 @@
       [lMla MlMla
        ## TODO: Remove this version ASAP and use one below.
        lla (for {@.old
-                 (: (($ 0) (List (List ($ 1))))
+                 (: ((:parameter 0) (List (List (:parameter 1))))
                     (monad.seq ! lMla))}
                 (monad.seq ! lMla))]
       (in (concat lla)))))
diff --git a/stdlib/source/library/lux/data/collection/row.lux b/stdlib/source/library/lux/data/collection/row.lux
index b5bbcbe30..7ce9802d6 100644
--- a/stdlib/source/library/lux/data/collection/row.lux
+++ b/stdlib/source/library/lux/data/collection/row.lux
@@ -218,7 +218,7 @@
             ## 1-level taller.
             (|> row
                 (set@ #root (|> (for {@.old
-                                      (: (Hierarchy ($ 0))
+                                      (: (Hierarchy (:parameter 0))
                                          (new_hierarchy []))}
                                      (new_hierarchy []))
                                 (array.write! 0 (#Hierarchy (get@ #root row)))
@@ -285,7 +285,7 @@
     (if (within_bounds? row idx)
       (#try.Success (if (n.>= (tail_off row_size) idx)
                       (update@ #tail (for {@.old
-                                           (: (-> (Base ($ 0)) (Base ($ 0)))
+                                           (: (-> (Base (:parameter 0)) (Base (:parameter 0)))
                                               (|>> array.clone (array.write! (branch_idx idx) val)))}
                                           (|>> array.clone (array.write! (branch_idx idx) val)))
                                row)
diff --git a/stdlib/source/library/lux/data/collection/tree/zipper.lux b/stdlib/source/library/lux/data/collection/tree/zipper.lux
index 4c1def087..45e3a109e 100644
--- a/stdlib/source/library/lux/data/collection/tree/zipper.lux
+++ b/stdlib/source/library/lux/data/collection/tree/zipper.lux
@@ -102,7 +102,8 @@
     [family (get@ #family zipper)]
     (in (let [(^slots [#parent #lefts #rights]) family]
           (for {@.old
-                (update@ #node (: (-> (Tree ($ 0)) (Tree ($ 0)))
+                (update@ #node (: (-> (Tree (:parameter 0))
+                                      (Tree (:parameter 0)))
                                   (set@ #//.children (list\compose (list.reverse lefts)
                                                                    (#.Item (get@ #node zipper)
                                                                            rights))))
diff --git a/stdlib/source/library/lux/data/color.lux b/stdlib/source/library/lux/data/color.lux
index 325d94db0..482b6435d 100644
--- a/stdlib/source/library/lux/data/color.lux
+++ b/stdlib/source/library/lux/data/color.lux
@@ -5,9 +5,18 @@
      [equivalence (#+ Equivalence)]
      [monoid (#+ Monoid)]
      ["." hash (#+ Hash)]]
+    [control
+     [parser
+      ["<.>" code]]]
     [data
+     ["." text
+      ["%" format (#+ format)]]
      [collection
       ["." list ("#\." functor)]]]
+    [macro
+     [syntax (#+ syntax:)]
+     ["." template]
+     ["." code]]
     ["." math
      [number
       ["n" nat]
@@ -21,7 +30,8 @@
 (def: rgb 256)
 (def: top (dec rgb))
 
-(def: rgb_factor (|> top .int int.frac))
+(def: rgb_factor
+  (|> top .int int.frac))
 
 (def: down
   (-> Nat Frac)
@@ -32,25 +42,31 @@
   (|>> (f.* rgb_factor) f.int .nat))
 
 (type: #export RGB
+  {#.doc (doc "Red-Green-Blue color format.")}
   {#red Nat
    #green Nat
    #blue Nat})
 
 (type: #export HSL
+  {#.doc (doc "Hue-Saturation-Lightness color format.")}
   [Frac Frac Frac])
 
 (type: #export CMYK
+  {#.doc (doc "Cyan-Magenta-Yellow-Key color format.")}
   {#cyan Frac
    #magenta Frac
    #yellow Frac
    #key Frac})
 
 (type: #export HSB
+  {#.doc (doc "Hue-Saturation-Brightness color format.")}
   [Frac Frac Frac])
 
 (abstract: #export Color
   RGB
 
+  {#.doc (doc "A color value, independent of color format.")}
+
   (def: #export (of_rgb [red green blue])
     (-> RGB Color)
     (:abstraction {#red (n.% ..rgb red)
@@ -84,11 +100,13 @@
             b))))
 
   (def: #export black
+    Color
     (..of_rgb {#red 0
                #green 0
                #blue 0}))
 
   (def: #export white
+    Color
     (..of_rgb {#red ..top
                #green ..top
                #blue ..top}))
@@ -110,6 +128,7 @@
     (|> ..top (n.- value)))
 
   (def: #export (complement color)
+    {#.doc (doc "The opposite color.")}
     (-> Color Color)
     (let [[red green blue] (:representation color)]
       (:abstraction {#red (complement' red)
@@ -316,11 +335,11 @@
      (-> Frac Color Color)
      (..interpolate ratio <target> color))]
 
-  [darker   black]
-  [brighter white]
+  [darker   ..black]
+  [brighter ..white]
   )
 
-(template [<name> <op>]
+(template [<op> <name>]
   [(def: #export (<name> ratio color)
      (-> Frac Color Color)
      (let [[hue saturation luminance] (to_hsl color)]
@@ -330,8 +349,8 @@
                     (f.min +1.0))
                 luminance])))]
 
-  [saturate    f.+]
-  [de_saturate f.-]
+  [f.+ saturate]
+  [f.- de_saturate]
   )
 
 (def: #export (gray_scale color)
@@ -341,17 +360,23 @@
              +0.0
              luminance])))
 
+(syntax: (color_scheme_documentation {name <code>.local_identifier})
+  (let [name (text.replace_all "_" "-" name)
+        g!documentation (code.text (format "A " name " color scheme."))]
+    (in (list (` {#.doc (.doc (~ g!documentation))})))))
+
 (template [<name> <1> <2>]
-  [(def: #export (<name> color)
-     (-> Color [Color Color Color])
-     (let [[hue saturation luminance] (to_hsl color)]
-       [color
-        (of_hsl [(|> hue (f.+ <1>) ..normal)
-                 saturation
-                 luminance])
-        (of_hsl [(|> hue (f.+ <2>) ..normal)
-                 saturation
-                 luminance])]))]
+  [(`` (def: #export (<name> color)
+         (~~ (..color_scheme_documentation <name>))
+         (-> Color [Color Color Color])
+         (let [[hue saturation luminance] (to_hsl color)]
+           [color
+            (of_hsl [(|> hue (f.+ <1>) ..normal)
+                     saturation
+                     luminance])
+            (of_hsl [(|> hue (f.+ <2>) ..normal)
+                     saturation
+                     luminance])])))]
 
   [triad            (|> +1.0 (f./ +3.0)) (|> +2.0 (f./ +3.0))]
   [clash            (|> +1.0 (f./ +4.0)) (|> +3.0 (f./ +4.0))]
@@ -359,19 +384,20 @@
   )
 
 (template [<name> <1> <2> <3>]
-  [(def: #export (<name> color)
-     (-> Color [Color Color Color Color])
-     (let [[hue saturation luminance] (to_hsb color)]
-       [color
-        (of_hsb [(|> hue (f.+ <1>) ..normal)
-                 saturation
-                 luminance])
-        (of_hsb [(|> hue (f.+ <2>) ..normal)
-                 saturation
-                 luminance])
-        (of_hsb [(|> hue (f.+ <3>) ..normal)
-                 saturation
-                 luminance])]))]
+  [(`` (def: #export (<name> color)
+         (~~ (..color_scheme_documentation <name>))
+         (-> Color [Color Color Color Color])
+         (let [[hue saturation luminance] (to_hsb color)]
+           [color
+            (of_hsb [(|> hue (f.+ <1>) ..normal)
+                     saturation
+                     luminance])
+            (of_hsb [(|> hue (f.+ <2>) ..normal)
+                     saturation
+                     luminance])
+            (of_hsb [(|> hue (f.+ <3>) ..normal)
+                     saturation
+                     luminance])])))]
 
   [square   (|> +1.0 (f./ +4.0))  (|> +2.0 (f./ +4.0))  (|> +3.0 (f./ +4.0))]
   [tetradic (|> +2.0 (f./ +12.0)) (|> +6.0 (f./ +12.0)) (|> +8.0 (f./ +12.0))]
@@ -383,43 +409,55 @@
 (type: #export Palette
   (-> Spread Nat Color (List Color)))
 
-(def: #export (analogous spread variations color)
-  (-> Spread Nat Color (List Color))
-  (let [[hue saturation brightness] (to_hsb color)
-        spread (..normal spread)]
-    (list\map (function (_ idx)
-                (of_hsb [(|> idx inc .int int.frac (f.* spread) (f.+ hue) ..normal)
-                         saturation
-                         brightness]))
-              (list.indices variations))))
-
-(def: #export (monochromatic spread variations color)
-  (-> Spread Nat Color (List Color))
-  (let [[hue saturation brightness] (to_hsb color)
-        spread (..normal spread)]
-    (|> (list.indices variations)
-        (list\map (|>> inc .int int.frac
-                       (f.* spread)
-                       (f.+ brightness)
-                       ..normal
-                       [hue saturation]
-                       of_hsb)))))
+(syntax: (palette_documentation {name <code>.local_identifier})
+  (let [name (text.replace_all "_" "-" name)
+        g!documentation (code.text (format "A " name " palette."))]
+    (in (list (` {#.doc (.doc (~ g!documentation))})))))
+
+(`` (def: #export (analogous spread variations color)
+      (~~ (..palette_documentation analogous))
+      Palette
+      (let [[hue saturation brightness] (to_hsb color)
+            spread (..normal spread)]
+        (list\map (function (_ idx)
+                    (of_hsb [(|> idx inc .int int.frac (f.* spread) (f.+ hue) ..normal)
+                             saturation
+                             brightness]))
+                  (list.indices variations)))))
+
+(`` (def: #export (monochromatic spread variations color)
+      (~~ (..palette_documentation monochromatic))
+      Palette
+      (let [[hue saturation brightness] (to_hsb color)
+            spread (..normal spread)]
+        (|> (list.indices variations)
+            (list\map (|>> inc .int int.frac
+                           (f.* spread)
+                           (f.+ brightness)
+                           ..normal
+                           [hue saturation]
+                           of_hsb))))))
 
 (type: #export Alpha
+  {#.doc (doc "The degree of transparency of a pigment.")}
   Rev)
 
 (def: #export transparent
+  {#.doc (doc "The maximum degree of transparency.")}
   Alpha
   rev\bottom)
 
 (def: #export translucent
+  {#.doc (doc "The average degree of transparency.")}
   Alpha
   .5)
 
 (def: #export opaque
+  {#.doc (doc "The minimum degree of transparency.")}
   Alpha
   rev\top)
 
 (type: #export Pigment
+  {#.doc (doc "A color with some degree of transparency.")}
   {#color Color
    #alpha Alpha})
diff --git a/stdlib/source/library/lux/data/format/tar.lux b/stdlib/source/library/lux/data/format/tar.lux
index d5dad8d9b..52e37991b 100644
--- a/stdlib/source/library/lux/data/format/tar.lux
+++ b/stdlib/source/library/lux/data/format/tar.lux
@@ -33,7 +33,8 @@
     [type
      abstract]]])
 
-(type: Size Nat)
+(type: Size
+  Nat)
 
 (def: octal_size Size 8)
 
@@ -118,11 +119,11 @@
     [pre_end <binary>.bits/8
      end <binary>.bits/8
      _ (let [expected (`` (char (~~ (static ..blank))))]
-         (<>.assert (exception.construct ..wrong_character [expected pre_end])
-                    (n.= expected pre_end)))
+         (<>.assertion (exception.construct ..wrong_character [expected pre_end])
+                       (n.= expected pre_end)))
      _ (let [expected (`` (char (~~ (static ..null))))]
-         (<>.assert (exception.construct ..wrong_character [expected end])
-                    (n.= expected end)))]
+         (<>.assertion (exception.construct ..wrong_character [expected end])
+                       (n.= expected end)))]
     (in [])))
 
 (def: small_parser
@@ -143,8 +144,8 @@
      digits (<>.lift (\ utf8.codec decode digits))
      end <binary>.bits/8
      _ (let [expected (`` (char (~~ (static ..blank))))]
-         (<>.assert (exception.construct ..wrong_character [expected end])
-                    (n.= expected end)))]
+         (<>.assertion (exception.construct ..wrong_character [expected end])
+                       (n.= expected end)))]
     (<>.lift
      (do {! try.monad}
        [value (\ n.octal decode digits)]
@@ -276,8 +277,8 @@
          [string (<binary>.segment <size>)
           end <binary>.bits/8
           #let [expected (`` (char (~~ (static ..null))))]
-          _ (<>.assert (exception.construct ..wrong_character [expected end])
-                       (n.= expected end))]
+          _ (<>.assertion (exception.construct ..wrong_character [expected end])
+                          (n.= expected end))]
          (<>.lift
           (do {! try.monad}
             [ascii (..un_pad string)
@@ -318,8 +319,8 @@
       [string (<binary>.segment ..magic_size)
        end <binary>.bits/8
        #let [expected (`` (char (~~ (static ..null))))]
-       _ (<>.assert (exception.construct ..wrong_character [expected end])
-                    (n.= expected end))]
+       _ (<>.assertion (exception.construct ..wrong_character [expected end])
+                       (n.= expected end))]
       (<>.lift
        (\ try.monad map (|>> :abstraction)
           (\ utf8.codec decode string)))))
@@ -763,8 +764,8 @@
      [actual checksum_code] ..checksum_parser
      _ (let [expected (expected_checksum checksum_code binary_header)]
          (<>.lift
-          (exception.assert ..wrong_checksum [expected actual]
-                            (n.= expected actual))))
+          (exception.assertion ..wrong_checksum [expected actual]
+                               (n.= expected actual))))
      link_flag ..link_flag_parser
      link_name ..path_parser
      magic ..magic_parser
@@ -797,8 +798,8 @@
   (-> Link_Flag (Parser File))
   (do <>.monad
     [header ..header_parser
-     _ (<>.assert (exception.construct ..wrong_link_flag [expected (get@ #link_flag header)])
-                  (is? expected (get@ #link_flag header)))
+     _ (<>.assertion (exception.construct ..wrong_link_flag [expected (get@ #link_flag header)])
+                     (is? expected (get@ #link_flag header)))
      #let [size (get@ #size header)
            rounded_size (..rounded_content_size size)]
      content (<binary>.segment (..from_big size))
@@ -824,9 +825,9 @@
   (do <>.monad
     [header ..header_parser
      _ (<>.lift
-        (exception.assert ..wrong_link_flag [expected (get@ #link_flag header)]
-                          (n.= (..link_flag expected)
-                               (..link_flag (get@ #link_flag header)))))]
+        (exception.assertion ..wrong_link_flag [expected (get@ #link_flag header)]
+                             (n.= (..link_flag expected)
+                                  (..link_flag (get@ #link_flag header)))))]
     (in (extractor header))))
 
 (def: entry_parser
@@ -850,8 +851,8 @@
     [block (<binary>.segment ..block_size)]
     (let [actual (..checksum block)]
       (<>.lift
-       (exception.assert ..wrong_checksum [0 actual]
-                         (n.= 0 actual))))))
+       (exception.assertion ..wrong_checksum [0 actual]
+                            (n.= 0 actual))))))
 
 (exception: #export invalid_end_of_archive)
 
@@ -861,8 +862,8 @@
     [_ (<>.at_most 2 end_of_archive_block_parser)
      done? <binary>.end?]
     (<>.lift
-     (exception.assert ..invalid_end_of_archive []
-                       done?))))
+     (exception.assertion ..invalid_end_of_archive []
+                          done?))))
 
 (def: #export parser
   (Parser Tar)
diff --git a/stdlib/source/library/lux/data/format/xml.lux b/stdlib/source/library/lux/data/format/xml.lux
index 468100e5b..b7cf0323d 100644
--- a/stdlib/source/library/lux/data/format/xml.lux
+++ b/stdlib/source/library/lux/data/format/xml.lux
@@ -31,6 +31,7 @@
   (Dictionary Attribute Text))
 
 (def: #export attributes
+  {#.doc (doc "An empty set of XML attributes.")}
   Attrs
   (dictionary.new name.hash))
 
@@ -126,10 +127,10 @@
                 ..spaced^
                 (<>.after (<text>.this "/"))
                 (<text>.enclosed ["<" ">"]))]
-    (<>.assert ($_ text\compose "Close tag does not match open tag." text.new_line
-                   "Expected: " (name\encode expected) text.new_line
-                   "  Actual: " (name\encode actual) text.new_line)
-               (name\= expected actual))))
+    (<>.assertion ($_ text\compose "Close tag does not match open tag." text.new_line
+                      "Expected: " (name\encode expected) text.new_line
+                      "  Actual: " (name\encode actual) text.new_line)
+                  (name\= expected actual))))
 
 (def: comment^
   (Parser Text)
@@ -210,12 +211,14 @@
       (text.replace_all text.double_quote "&quot;")))
 
 (def: #export (tag [namespace name])
+  {#.doc (doc "The text format of a XML tag.")}
   (-> Tag Text)
   (case namespace
     "" name
     _ ($_ text\compose namespace ..namespace_separator name)))
 
 (def: #export attribute
+  {#.doc (doc "The text format of a XML attribute.")}
   (-> Attribute Text)
   ..tag)
 
diff --git a/stdlib/source/library/lux/data/identity.lux b/stdlib/source/library/lux/data/identity.lux
index 521f66e3e..851504816 100644
--- a/stdlib/source/library/lux/data/identity.lux
+++ b/stdlib/source/library/lux/data/identity.lux
@@ -10,6 +10,7 @@
      ["." function]]]])
 
 (type: #export (Identity a)
+  {#.doc (doc "A value, as is, without any extra structure super-imposed on it.")}
   a)
 
 (implementation: #export functor
diff --git a/stdlib/source/library/lux/data/lazy.lux b/stdlib/source/library/lux/data/lazy.lux
index d3283cfc8..d4b345f87 100644
--- a/stdlib/source/library/lux/data/lazy.lux
+++ b/stdlib/source/library/lux/data/lazy.lux
@@ -20,6 +20,9 @@
 (abstract: #export (Lazy a)
   (-> [] a)
 
+  {#.doc (doc "A value specified by an expression that is calculated only at the last moment possible."
+              "Afterwards, the value is cached for future reference.")}
+
   (def: (lazy' generator)
     (All [a] (-> (-> [] a) (Lazy a)))
     (let [cache (atom.atom #.None)]
@@ -33,20 +36,21 @@
                           (exec (io.run (atom.compare_and_swap _ (#.Some value) cache))
                             value)))))))
 
-  (def: #export (value l_value)
+  (def: #export (value lazy)
     (All [a] (-> (Lazy a) a))
-    ((:representation l_value) [])))
+    ((:representation lazy) [])))
 
-(syntax: #export (lazy expr)
+(syntax: #export (lazy expression)
+  {#.doc (doc "Specifies a lazy value by providing the expression that computes it.")}
   (with_gensyms [g!_]
-    (in (list (` ((~! lazy') (function ((~ g!_) (~ g!_)) (~ expr))))))))
+    (in (list (` ((~! lazy') (function ((~ g!_) (~ g!_)) (~ expression))))))))
 
-(implementation: #export (equivalence (^open "_\."))
+(implementation: #export (equivalence (^open "\."))
   (All [a] (-> (Equivalence a) (Equivalence (Lazy a))))
   
   (def: (= left right)
-    (_\= (..value left)
-         (..value right))))
+    (\= (..value left)
+        (..value right))))
 
 (implementation: #export functor
   (Functor Lazy)
diff --git a/stdlib/source/library/lux/data/maybe.lux b/stdlib/source/library/lux/data/maybe.lux
index b0cf1960e..7d6ac8dfa 100644
--- a/stdlib/source/library/lux/data/maybe.lux
+++ b/stdlib/source/library/lux/data/maybe.lux
@@ -111,6 +111,7 @@
         Mma))))
 
 (def: #export (lift monad)
+  {#.doc (doc "Wraps a monadic value with Maybe machinery.")}
   (All [M a] (-> (Monad M) (-> (M a) (M (Maybe a)))))
   (\ monad map (\ ..monad in)))
 
@@ -121,6 +122,7 @@
               (else +20 (#.Some +10))
               "=>"
               +10
+              --------------------------
               (else +20 #.None)
               "=>"
               +20)}
@@ -138,6 +140,9 @@
     (#.Left "Wrong syntax for else")))
 
 (def: #export assume
+  {#.doc (doc "Assumes that a Maybe value is a #.Some and yields its value."
+              "Raises/throws a runtime error otherwise."
+              "WARNING: Use with caution.")}
   (All [a] (-> (Maybe a) a))
   (|>> (..else (undefined))))
 
diff --git a/stdlib/source/library/lux/data/text/encoding.lux b/stdlib/source/library/lux/data/text/encoding.lux
index 3ecb5b4e0..8829d7d92 100644
--- a/stdlib/source/library/lux/data/text/encoding.lux
+++ b/stdlib/source/library/lux/data/text/encoding.lux
@@ -10,7 +10,9 @@
   Text
 
   (template [<name> <encoding>]
-    [(def: #export <name> Encoding (:abstraction <encoding>))]
+    [(def: #export <name>
+       Encoding
+       (:abstraction <encoding>))]
 
     [ascii "ASCII"]
 
diff --git a/stdlib/source/library/lux/data/text/encoding/utf8.lux b/stdlib/source/library/lux/data/text/encoding/utf8.lux
index b24c88837..7e5c8a4e2 100644
--- a/stdlib/source/library/lux/data/text/encoding/utf8.lux
+++ b/stdlib/source/library/lux/data/text/encoding/utf8.lux
@@ -158,6 +158,7 @@
               #try.Success)})))
 
 (implementation: #export codec
+  {#.doc (doc "A codec for binary encoding of text as UTF-8.")}
   (Codec Binary Text)
   
   (def: encode ..encode)
diff --git a/stdlib/source/library/lux/data/text/escape.lux b/stdlib/source/library/lux/data/text/escape.lux
index 9ca9ecfe1..6c78dc7d5 100644
--- a/stdlib/source/library/lux/data/text/escape.lux
+++ b/stdlib/source/library/lux/data/text/escape.lux
@@ -110,6 +110,7 @@
      post_limit]))
 
 (def: #export (escape text)
+  {#.doc (doc "Yields a escaped version of the text.")}
   (-> Text Text)
   (loop [offset 0
          previous ""
@@ -191,6 +192,8 @@
     (exception.except ..invalid_unicode_escape [current offset])))
 
 (def: #export (un_escape text)
+  {#.doc (doc "Yields an un-escaped text."
+              "Fails if it was improperly escaped.")}
   (-> Text (Try Text))
   (loop [offset 0
          previous ""
@@ -236,6 +239,7 @@
                       _ (format previous current))))))
 
 (syntax: #export (escaped {literal <code>.text})
+  {#.doc (doc "If given a escaped text literal, expands to an un-escaped version.")}
   (case (..un_escape literal)
     (#try.Success un_escaped)
     (in (list (code.text un_escaped)))
diff --git a/stdlib/source/library/lux/data/text/regex.lux b/stdlib/source/library/lux/data/text/regex.lux
index ccbb1417a..1e2128275 100644
--- a/stdlib/source/library/lux/data/text/regex.lux
+++ b/stdlib/source/library/lux/data/text/regex.lux
@@ -82,7 +82,7 @@
   (-> Text (Parser Code))
   (do <>.monad
     [name (<text>.enclosed ["\@<" ">"] (name^ current_module))]
-    (in (` (: (Parser Text) (~ (code.identifier name)))))))
+    (in (` (: ((~! <text>.Parser) Text) (~ (code.identifier name)))))))
 
 (def: re_range^
   (Parser Code)
@@ -90,7 +90,7 @@
     [from (|> regex_char^ (\ ! map (|>> (//.nth 0) maybe.assume)))
      _ (<text>.this "-")
      to (|> regex_char^ (\ ! map (|>> (//.nth 0) maybe.assume)))]
-    (in (` (<text>.range (~ (code.nat from)) (~ (code.nat to)))))))
+    (in (` ((~! <text>.range) (~ (code.nat from)) (~ (code.nat to)))))))
 
 (def: re_char^
   (Parser Code)
@@ -102,7 +102,7 @@
   (Parser Code)
   (do <>.monad
     [options (<text>.many escaped_char^)]
-    (in (` (<text>.one_of (~ (code.text options)))))))
+    (in (` ((~! <text>.one_of) (~ (code.text options)))))))
 
 (def: re_user_class^'
   (Parser Code)
@@ -112,8 +112,8 @@
                         re_range^
                         re_options^))]
     (in (case negate?
-          (#.Some _) (` (<text>.not ($_ <>.either (~+ parts))))
-          #.None     (` ($_ <>.either (~+ parts)))))))
+          (#.Some _) (` ((~! <text>.not) ($_ ((~! <>.either)) (~+ parts))))
+          #.None     (` ($_ ((~! <>.either)) (~+ parts)))))))
 
 (def: re_user_class^
   (Parser Code)
@@ -158,22 +158,22 @@
   (do <>.monad
     []
     ($_ <>.either
-        (<>.after (<text>.this ".") (in (` <text>.any)))
-        (<>.after (<text>.this "\d") (in (` <text>.decimal)))
-        (<>.after (<text>.this "\D") (in (` (<text>.not <text>.decimal))))
-        (<>.after (<text>.this "\s") (in (` <text>.space)))
-        (<>.after (<text>.this "\S") (in (` (<text>.not <text>.space))))
+        (<>.after (<text>.this ".") (in (` (~! <text>.any))))
+        (<>.after (<text>.this "\d") (in (` (~! <text>.decimal))))
+        (<>.after (<text>.this "\D") (in (` ((~! <text>.not) (~! <text>.decimal)))))
+        (<>.after (<text>.this "\s") (in (` (~! <text>.space))))
+        (<>.after (<text>.this "\S") (in (` ((~! <text>.not) (~! <text>.space)))))
         (<>.after (<text>.this "\w") (in (` (~! word^))))
-        (<>.after (<text>.this "\W") (in (` (<text>.not (~! word^)))))
-
-        (<>.after (<text>.this "\p{Lower}") (in (` <text>.lower)))
-        (<>.after (<text>.this "\p{Upper}") (in (` <text>.upper)))
-        (<>.after (<text>.this "\p{Alpha}") (in (` <text>.alpha)))
-        (<>.after (<text>.this "\p{Digit}") (in (` <text>.decimal)))
-        (<>.after (<text>.this "\p{Alnum}") (in (` <text>.alpha_num)))
-        (<>.after (<text>.this "\p{Space}") (in (` <text>.space)))
-        (<>.after (<text>.this "\p{HexDigit}") (in (` <text>.hexadecimal)))
-        (<>.after (<text>.this "\p{OctDigit}") (in (` <text>.octal)))
+        (<>.after (<text>.this "\W") (in (` ((~! <text>.not) (~! word^)))))
+
+        (<>.after (<text>.this "\p{Lower}") (in (` (~! <text>.lower))))
+        (<>.after (<text>.this "\p{Upper}") (in (` (~! <text>.upper))))
+        (<>.after (<text>.this "\p{Alpha}") (in (` (~! <text>.alpha))))
+        (<>.after (<text>.this "\p{Digit}") (in (` (~! <text>.decimal))))
+        (<>.after (<text>.this "\p{Alnum}") (in (` (~! <text>.alpha_num))))
+        (<>.after (<text>.this "\p{Space}") (in (` (~! <text>.space))))
+        (<>.after (<text>.this "\p{HexDigit}") (in (` (~! <text>.hexadecimal))))
+        (<>.after (<text>.this "\p{OctDigit}") (in (` (~! <text>.octal))))
         (<>.after (<text>.this "\p{Blank}") (in (` (~! blank^))))
         (<>.after (<text>.this "\p{ASCII}") (in (` (~! ascii^))))
         (<>.after (<text>.this "\p{Contrl}") (in (` (~! control^))))
@@ -220,14 +220,14 @@
      quantifier (<text>.one_of "?*+")]
     (case quantifier
       "?"
-      (in (` (<>.else "" (~ base))))
+      (in (` ((~! <>.else) "" (~ base))))
       
       "*"
-      (in (` ((~! join_text^) (<>.some (~ base)))))
+      (in (` ((~! join_text^) ((~! <>.some) (~ base)))))
       
       ## "+"
       _
-      (in (` ((~! join_text^) (<>.many (~ base)))))
+      (in (` ((~! join_text^) ((~! <>.many) (~ base)))))
       )))
 
 (exception: #export (incorrect_quantification {from Nat} {to Nat})
@@ -243,20 +243,21 @@
         ($_ <>.either
             (do !
               [[from to] (<>.and number^ (<>.after (<text>.this ",") number^))
-               _ (<>.assert (exception.construct ..incorrect_quantification [from to])
-                            (n.<= to from))]
-              (in (` ((~! join_text^) (<>.between (~ (code.nat from))
-                                                  (~ (code.nat (n.- from to)))
-                                                  (~ base))))))
+               _ (<>.assertion (exception.construct ..incorrect_quantification [from to])
+                               (n.<= to from))]
+              (in (` ((~! join_text^) ((~! <>.between)
+                                       (~ (code.nat from))
+                                       (~ (code.nat (n.- from to)))
+                                       (~ base))))))
             (do !
               [limit (<>.after (<text>.this ",") number^)]
-              (in (` ((~! join_text^) (<>.at_most (~ (code.nat limit)) (~ base))))))
+              (in (` ((~! join_text^) ((~! <>.at_most) (~ (code.nat limit)) (~ base))))))
             (do !
               [limit (<>.before (<text>.this ",") number^)]
-              (in (` ((~! join_text^) (<>.at_least (~ (code.nat limit)) (~ base))))))
+              (in (` ((~! join_text^) ((~! <>.at_least) (~ (code.nat limit)) (~ base))))))
             (do !
               [limit number^]
-              (in (` ((~! join_text^) (<>.exactly (~ (code.nat limit)) (~ base))))))))))
+              (in (` ((~! join_text^) ((~! <>.exactly) (~ (code.nat limit)) (~ base))))))))))
 
 (def: (re_quantified^ current_module)
   (-> Text (Parser Code))
@@ -318,10 +319,10 @@
     (in [(if capturing?
            (list.size names)
            0)
-         (` (do <>.monad
-              [(~ (' #let)) [(~ g!total) ""]
-               (~+ (|> steps list.reverse list\join))]
-              ((~ (' in)) [(~ g!total) (~+ (list.reverse names))])))])
+         (` ((~! do) (~! <>.monad)
+             [(~ (' #let)) [(~ g!total) ""]
+              (~+ (|> steps list.reverse list\join))]
+             ((~ (' in)) [(~ g!total) (~+ (list.reverse names))])))])
     ))
 
 (def: (unflatten^ lexer)
diff --git a/stdlib/source/library/lux/data/text/unicode/block.lux b/stdlib/source/library/lux/data/text/unicode/block.lux
index e67eb3ae3..5c4d9ec76 100644
--- a/stdlib/source/library/lux/data/text/unicode/block.lux
+++ b/stdlib/source/library/lux/data/text/unicode/block.lux
@@ -6,6 +6,15 @@
      [hash (#+ Hash)]
      [monoid (#+ Monoid)]
      ["." interval (#+ Interval)]]
+    [control
+     [parser
+      ["<.>" code]]]
+    [data
+     ["." text]]
+    [macro
+     [syntax (#+ syntax:)]
+     ["." template]
+     ["." code]]
     [math
      [number (#+ hex)
       ["n" nat ("#\." interval)]
@@ -16,6 +25,8 @@
 
 (abstract: #export Block
   (Interval Char)
+  
+  {#.doc (doc "A block of valid unicode characters.")}
 
   (implementation: #export monoid
     (Monoid Block)
@@ -32,9 +43,9 @@
                            (n.max (\ left top)
                                   (\ right top)))))))
 
-  (def: #export (block start end)
-    (-> Char Char Block)
-    (:abstraction (interval.between n.enum (n.min start end) (n.max start end))))
+  (def: #export (block start additional)
+    (-> Char Nat Block)
+    (:abstraction (interval.between n.enum start (n.+ additional start))))
 
   (template [<name> <slot>]
     [(def: #export <name>
@@ -71,8 +82,18 @@
     (i64.or (i64.left_shifted 32 (..start value))
             (..end value))))
 
+(syntax: (block_name {name <code>.local_identifier})
+  (in (list (code.text (text.replace_all "_" " " name)))))
+
 (template [<name> <start> <end>]
-  [(def: #export <name> Block (..block (hex <start>) (hex <end>)))]
+  [(with_expansions [<block_name> (..block_name <name>)
+                     <documentation> (template.text [<start> "-" <end> " | " <block_name>])]
+     (def: #export <name>
+       {#.doc (doc <documentation>)}
+       Block
+       (let [start (hex <start>)
+             end (hex <end>)]
+         (..block start (n.- start end)))))]
 
   ## Normal blocks
   [basic_latin                             "0000"  "007F"]
diff --git a/stdlib/source/library/lux/data/text/unicode/set.lux b/stdlib/source/library/lux/data/text/unicode/set.lux
index 1f2d411f9..0a5aa6ce8 100644
--- a/stdlib/source/library/lux/data/text/unicode/set.lux
+++ b/stdlib/source/library/lux/data/text/unicode/set.lux
@@ -200,11 +200,17 @@
         ..non_character
         ))
 
-  (def: #export (range set)
-    (-> Set [Char Char])
-    (let [tag (tree.tag (:representation set))]
-      [(//block.start tag)
-       (//block.end tag)]))
+  (def: #export start
+    (-> Set Char)
+    (|>> :representation
+         tree.tag
+         //block.start))
+
+  (def: #export end
+    (-> Set Char)
+    (|>> :representation
+         tree.tag
+         //block.end))
 
   (def: #export (member? set character)
     (-> Set Char Bit)
@@ -229,6 +235,7 @@
 
 (template [<name> <blocks>]
   [(def: #export <name>
+     Set
      (..set <blocks>))]
 
   [ascii           [//block.basic_latin (list)]]