Documentation improvements.

10 files changed, 119 insertions, 77 deletions

diff --git a/stdlib/source/documentation/lux.lux b/stdlib/source/documentation/lux.lux
index 184049d89..94ccb3b38 100644
--- a/stdlib/source/documentation/lux.lux
+++ b/stdlib/source/documentation/lux.lux
@@ -290,8 +290,10 @@
      [(def: .public <name>
         (-> Int Int)
         (+ <diff>))]
+     
      [++ +1]
-     [-- -1])])
+     [-- -1]
+     )])
 
 (documentation: /.not
   "Bit negation."
@@ -599,7 +601,7 @@
        ["M" monad "*"]]
       [data
        maybe
-       ["." name ("#/." codec)]]
+       ["." name ("#\." codec)]]
       [macro
        code]]
      [//
@@ -767,9 +769,9 @@
 
 (documentation: /.name_of
   "Given an identifier or a tag, gives back a 2 tuple with the module and name parts, both as Text."
-  [(name_of #.doc)
+  [(name_of #..doc)
    "=>"
-   ["library/lux" "doc"]])
+   ["documentation/lux" "doc"]])
 
 (documentation: /.:parameter
   (format "WARNING: Please stay away from this macro; it's very likely to be removed in a future version of Lux."
@@ -856,9 +858,11 @@
 (documentation: /.for
   (format "Selects the appropriate code for a given target-platform when compiling Lux to it."
           \n "Look-up the available targets in library/lux/target.")
-  [(def: js "JavaScript")
+  [(def: js
+     "JavaScript")
+   
    (for {"JVM" (do jvm stuff)
-         ..js (do js stuff)}
+         js (do js stuff)}
         (do default stuff))])
 
 (documentation: /.``
diff --git a/stdlib/source/documentation/lux/data/format/json.lux b/stdlib/source/documentation/lux/data/format/json.lux
index cf3182daa..6bb637058 100644
--- a/stdlib/source/documentation/lux/data/format/json.lux
+++ b/stdlib/source/documentation/lux/data/format/json.lux
@@ -12,13 +12,18 @@
 
 (documentation: /.json
   "A simple way to produce JSON literals."
-  [(json #null)]
-  [(json #1)]
-  [(json +123.456)]
-  [(json "this is a string")]
-  [(json ["this" "is" "an" "array"])]
-  [(json {"this" "is"
-          "an" "object"})])
+  ["null"
+   (json #null)]
+  ["true"
+   (json #1)]
+  ["123.456"
+   (json +123.456)]
+  ["'this is a string'"
+   (json "this is a string")]
+  ["['this' 'is' 'an' 'array']"
+   (json ["this" "is" "an" "array"])]
+  ["{'this' 'is', 'an' 'object'}"
+   (json {"this" "is" "an" "object"})])
 
 (documentation: /.fields
   "Get all the fields in a JSON object."
diff --git a/stdlib/source/documentation/lux/macro/syntax/type/variable.lux b/stdlib/source/documentation/lux/macro/syntax/type/variable.lux
index 692c8523d..1512f5985 100644
--- a/stdlib/source/documentation/lux/macro/syntax/type/variable.lux
+++ b/stdlib/source/documentation/lux/macro/syntax/type/variable.lux
@@ -11,7 +11,7 @@
    ["." /]])
 
 (documentation: /.Variable
-  "A variable'S name.")
+  "A variable's name.")
 
 (documentation: /.parser
   "Parser for the common type variable/parameter used by many macros.")
diff --git a/stdlib/source/documentation/lux/math/infix.lux b/stdlib/source/documentation/lux/math/infix.lux
index 19d21669b..c542dcf99 100644
--- a/stdlib/source/documentation/lux/math/infix.lux
+++ b/stdlib/source/documentation/lux/math/infix.lux
@@ -16,11 +16,27 @@
           \n "If you want your binary function to work well with it."
           \n "Then take the argument to the right (y) as your first argument,"
           \n "and take the argument to the left (x) as your second argument.")
-  [(infix [x * +10])]
-  [(infix [[x + y] * [x - y]])]
-  [(infix [sin [x + y]])]
-  [(infix [[x < y] and [y < z]])]
-  [(infix [(* 3 9) gcd 450])])
+  ["Binary functions"
+   (infix [x * +10])
+   "=>"
+   (* +10 x)]
+  ["Nested infix"
+   (infix [[x + y] * [x - y]])
+   "=>"
+   (* (- y x) (+ y x))]
+  ["Unary functions"
+   (infix [sin [x + y]])
+   "=>"
+   (sin (+ y x))]
+  ["Also works with logic"
+   (infix [[x < y] and [y < z]])
+   "=>"
+   (and (< z y)
+        (< y x))]
+  ["Forms are left as-is"
+   (infix [(* 3 9) gcd 450])
+   "=>"
+   (gcd 450 (* 3 9))])
 
 (.def: .public documentation
   (.List $.Module)
diff --git a/stdlib/source/library/lux.lux b/stdlib/source/library/lux.lux
index 1043560c9..5b6a2ba6e 100644
--- a/stdlib/source/library/lux.lux
+++ b/stdlib/source/library/lux.lux
@@ -276,10 +276,11 @@
 ... (type: .public Code
 ...   (Ann Location (Code' (Ann Location))))
 ("lux def" Code
- (#Named ["library/lux" "Code"]
-         ({w
-           (#Apply (#Apply w Code') w)}
-          ("lux type check type" (#Apply Location Ann))))
+ ("lux type check type"
+  (#Named ["library/lux" "Code"]
+          ({w
+            (#Apply (#Apply w Code') w)}
+           ("lux type check type" (#Apply Location Ann)))))
  [dummy_location
   (#Record #End)]
  #1)
diff --git a/stdlib/source/library/lux/documentation.lux b/stdlib/source/library/lux/documentation.lux
index 4c4dd1bdc..2985309ae 100644
--- a/stdlib/source/library/lux/documentation.lux
+++ b/stdlib/source/library/lux/documentation.lux
@@ -171,13 +171,15 @@
 
 (def: (parameter_type_name id)
   (-> Nat Text)
-  (case (text.char id ..parameter_name_options)
-    (#.Some char)
-    (text.of_char char)
-
-    #.None
-    (format (parameter_type_name (n./ parameter_name_options_count id))
-            (parameter_type_name (n.% parameter_name_options_count id)))))
+  (format "_" (%.nat id))
+  ... (case (text.char id ..parameter_name_options)
+  ...   (#.Some char)
+  ...   (text.of_char char)
+
+  ...   #.None
+  ...   (format (parameter_type_name (n./ parameter_name_options_count id))
+  ...           (parameter_type_name (n.% parameter_name_options_count id))))
+  )
 
 (def: type_variable_names
   (Sequence Text)
@@ -206,10 +208,11 @@
         found
 
         _
-        (|> type_variable_names
-            (sequence.only (function (_ var_name)
-                             (not (list.member? text.equivalence type_function_arguments var_name))))
-            (sequence.item parameter_id))))      
+        (let [parameter_id (n.- (list.size type_function_arguments) parameter_id)]
+          (|> type_variable_names
+              (sequence.only (function (_ var_name)
+                               (not (list.member? text.equivalence type_function_arguments var_name))))
+              (sequence.item parameter_id)))))      
     type_function_name))
 
 (def: (level_parameters offset level)
@@ -221,12 +224,19 @@
         (enum.range n.enum 0)
         (list\each (|>> (n.+ (++ offset)) parameter_type_name)))))
 
-(def: (%type' level type_function_name module type)
-  (-> Nat Text Text Type Text)
+(def: (nested line_prefix body)
+  (-> Text Text Text)
+  (|> body
+      (text.all_split_by \n)
+      (list\each (text.prefix line_prefix))
+      (text.interposed \n)))
+
+(def: (%type' level type_function_name nestable? module type)
+  (-> Nat Text Bit Text Type Text)
   (case type
     (#.Primitive name params)
     (|> params
-        (list\each (|>> (%type' level type_function_name module)
+        (list\each (|>> (%type' level type_function_name false module)
                         (format " ")))
         (#.Item (%.text name))
         text.together
@@ -235,23 +245,23 @@
     (#.Sum _)
     (|> type
         type.flat_variant
-        (list\each (%type' level type_function_name module))
+        (list\each (%type' level type_function_name false module))
         (text.interposed " ")
         (text.enclosed ["(Or " ")"]))
 
     (#.Product _)
     (|> type
         type.flat_tuple
-        (list\each (%type' level type_function_name module))
+        (list\each (%type' level type_function_name false module))
         (text.interposed " ")
         (text.enclosed ["[" "]"]))
 
     (#.Function input output)
     (let [[ins out] (type.flat_function type)]
       (format  "(-> "
-               (|> ins (list\each (%type' level type_function_name module)) (text.interposed " "))
+               (|> ins (list\each (%type' level type_function_name false module)) (text.interposed " "))
                " "
-               (%type' level type_function_name module out)
+               (%type' level type_function_name false module out)
                ")"))
 
     (#.Parameter idx)
@@ -267,9 +277,11 @@
       [(<tag> _)
        (let [[level' body] (<flat> type)
              args (level_parameters level level')
-             body_doc (%type' (n.+ level level') type_function_name module body)]
+             body_doc (%type' (n.+ level level') type_function_name nestable? module body)]
          (format "(" <name> " " "(_ " (|> args (text.interposed " ")) ")"
-                 (format " " body_doc)
+                 (if nestable?
+                   (format \n (nested "  " body_doc))
+                   (format " " body_doc))
                  ")"))])
     ([#.UnivQ "All" type.flat_univ_q]
      [#.ExQ   "Ex"  type.flat_ex_q])
@@ -278,11 +290,17 @@
     type_function_name
 
     (^ (#.Apply (|recursion_dummy|) (#.UnivQ _ body)))
-    (format "(Rec " type_function_name " " (%type' level type_function_name module body) ")")
+    (format "(Rec " type_function_name
+            \n (nested " " (%type' level type_function_name nestable? module body))
+            ")")
 
     (#.Apply param fun)
     (let [[type_func type_arguments] (type.flat_application type)]
-      (format  "(" (%type' level type_function_name module type_func) " " (|> type_arguments (list\each (%type' level type_function_name module)) (text.interposed " ")) ")"))
+      (format  "(" (%type' level type_function_name false module type_func)
+               " " (|> type_arguments
+                       (list\each (%type' level type_function_name false module))
+                       (text.interposed " "))
+               ")"))
 
     (#.Named [_module _name] type)
     (cond (text\= module _module)
@@ -297,7 +315,7 @@
 
 (def: type
   (-> Text Type Text)
-  (%type' (-- 0) "?"))
+  (%type' (-- 0) "?" true))
 
 (def: (parameterized_type arity type)
   (-> Nat Type (Maybe Type))
@@ -310,18 +328,12 @@
         _
         #.None)))
 
-(def: (prefixed_lines prefix lines)
-  (-> Text Text Text)
-  (|> lines
-      (text.all_split_by text.new_line)
-      (list\each (|>> (format prefix)))
-      (text.interposed text.new_line)))
-
-(def: (type_definition' level type_function_info tags module type)
-  (-> Nat [Text (List Text)] (List Text) Text Type Text)
+(def: (type_definition' nestable? level arity type_function_info tags module type)
+  (-> Bit Nat Nat [Text (List Text)] (List Text) Text Type Text)
   (case tags
     (^ (list single_tag))
-    (format "(Record [#" single_tag " " (type_definition' level type_function_info #.None module type) "])")
+    (format "(Record" \n
+            " [#" single_tag " " (type_definition' false level arity type_function_info #.None module type) "])")
 
     _
     (case type
@@ -331,7 +343,7 @@
         (format "(primitive " (%.text name) ")")
 
         _
-        (format "(primitive " (%.text name) " " (|> params (list\each (type_definition' level type_function_info #.None module)) (text.interposed " ")) ")"))
+        (format "(primitive " (%.text name) " " (|> params (list\each (type_definition' false level arity type_function_info #.None module)) (text.interposed " ")) ")"))
 
       (#.Sum _)
       (let [members (type.flat_variant type)]
@@ -339,7 +351,7 @@
           #.End
           (format "(Or "
                   (|> members
-                      (list\each (type_definition' level type_function_info #.None module))
+                      (list\each (type_definition' false level arity type_function_info #.None module))
                       (text.interposed " "))
                   ")")
 
@@ -352,35 +364,35 @@
                              (let [types (type.flat_tuple type)]
                                (format " (#" t_name " "
                                        (|> types
-                                           (list\each (type_definition' level type_function_info #.None module))
+                                           (list\each (type_definition' false level arity type_function_info #.None module))
                                            (text.interposed " "))
                                        ")"))
 
                              _
-                             (format " (#" t_name " " (type_definition' level type_function_info #.None module type) ")"))))
-              (text.interposed text.new_line)
+                             (format " (#" t_name " " (type_definition' false level arity type_function_info #.None module type) ")"))))
+              (text.interposed \n)
               (text.enclosed [(format "(Variant" \n) ")"]))))
 
       (#.Product _)
       (let [members (type.flat_tuple type)]
         (case tags
           #.End
-          (format "[" (|> members (list\each (type_definition' level type_function_info #.None module)) (text.interposed " ")) "]")
+          (format "[" (|> members (list\each (type_definition' false level arity type_function_info #.None module)) (text.interposed " ")) "]")
 
           _
           (|> members
               (list.zipped/2 tags)
               (list\each (function (_ [t_name type])
-                           (format "#" t_name " " (type_definition' level type_function_info #.None module type))))
+                           (format "#" t_name " " (type_definition' false level arity type_function_info #.None module type))))
               (text.interposed (format \n "  "))
               (text.enclosed [" [" "]"])
               (text.enclosed [(format "(Record" \n) ")"]))))
 
       (#.Function input output)
       (let [[ins out] (type.flat_function type)]
-        (format  "(-> " (|> ins (list\each (type_definition' level type_function_info #.None module)) (text.interposed " "))
+        (format  "(-> " (|> ins (list\each (type_definition' false level arity type_function_info #.None module)) (text.interposed " "))
                  " "
-                 (type_definition' level type_function_info #.None module out)
+                 (type_definition' false level arity type_function_info #.None module out)
                  ")"))
 
       (#.Parameter idx)
@@ -395,18 +407,15 @@
       (^template [<tag> <name> <flat>]
         [(<tag> _)
          (let [[level' body] (<flat> type)
-               args (level_parameters level level')
-               body_doc (type_definition' (n.+ level level') type_function_info tags module body)
+               args (level_parameters (n.- arity level) level')
+               body_doc (type_definition' nestable? (n.+ level level') arity type_function_info tags module body)
                fn_name (case type_function_info
                          [fn_name #.End] fn_name
                          _ "_")]
            (format "(" <name> " " "(" fn_name " " (text.interposed " " args) ")"
-                   (case tags
-                     #.End
-                     (format " " body_doc)
-
-                     _
-                     (format text.new_line (prefixed_lines "  " body_doc)))
+                   (if nestable?
+                     (format \n (..nested "  " body_doc))
+                     (format " " body_doc))
                    ")"))])
       ([#.UnivQ "All" type.flat_univ_q]
        [#.ExQ   "Ex"  type.flat_ex_q])
@@ -416,7 +425,7 @@
       (product.left type_function_info)
 
       (^ (#.Apply (|recursion_dummy|) (#.UnivQ _ body)))
-      (|> (type_definition' level type_function_info tags module body)
+      (|> (type_definition' nestable? level arity type_function_info tags module body)
           (text.all_split_by \n)
           (list\each (text.prefix " "))
           (text.interposed \n)
@@ -425,9 +434,9 @@
 
       (#.Apply param fun)
       (let [[type_func type_arguments] (type.flat_application type)]
-        (format  "(" (type_definition' level type_function_info tags module type_func)
+        (format  "(" (type_definition' false level arity type_function_info tags module type_func)
                  " " (|> type_arguments
-                         (list\each (type_definition' level type_function_info #.None module))
+                         (list\each (type_definition' false level arity type_function_info #.None module))
                          (text.interposed " "))
                  ")"))
 
@@ -447,7 +456,7 @@
   (let [arity (list.size parameters)]
     (case (parameterized_type arity type)
       (#.Some type)
-      (type_definition' (-- arity) [name parameters] tags module type)
+      (type_definition' true (-- arity) arity [name parameters] tags module type)
 
       #.None
       (..type module type))))
diff --git a/stdlib/source/library/lux/math/number/complex.lux b/stdlib/source/library/lux/math/number/complex.lux
index 0846ed3a8..6aa8bae30 100644
--- a/stdlib/source/library/lux/math/number/complex.lux
+++ b/stdlib/source/library/lux/math/number/complex.lux
@@ -33,15 +33,19 @@
                 #..imaginary (~ (maybe.else (' +0.0) ?imaginary))]))))
 
 (def: .public i
+  Complex
   (..complex +0.0 +1.0))
 
 (def: .public +one
+  Complex
   (..complex +1.0 +0.0))
 
 (def: .public -one
+  Complex
   (..complex -1.0 +0.0))
 
 (def: .public zero
+  Complex
   (..complex +0.0 +0.0))
 
 (def: .public (not_a_number? complex)
diff --git a/stdlib/source/library/lux/math/number/i16.lux b/stdlib/source/library/lux/math/number/i16.lux
index b3e97cb84..1eaf89c0d 100644
--- a/stdlib/source/library/lux/math/number/i16.lux
+++ b/stdlib/source/library/lux/math/number/i16.lux
@@ -13,6 +13,7 @@
   (maybe.trusted (i64.sub 16)))
 
 (def: .public I16
+  Type
   (:by_example [size]
                (Sub size)
                ..sub
diff --git a/stdlib/source/library/lux/math/number/i32.lux b/stdlib/source/library/lux/math/number/i32.lux
index 34174ddec..bba3a2fb4 100644
--- a/stdlib/source/library/lux/math/number/i32.lux
+++ b/stdlib/source/library/lux/math/number/i32.lux
@@ -13,6 +13,7 @@
   (maybe.trusted (i64.sub 32)))
 
 (def: .public I32
+  Type
   (:by_example [size]
                (Sub size)
                ..sub
diff --git a/stdlib/source/library/lux/math/number/i8.lux b/stdlib/source/library/lux/math/number/i8.lux
index a1d766e75..b5fa6f6aa 100644
--- a/stdlib/source/library/lux/math/number/i8.lux
+++ b/stdlib/source/library/lux/math/number/i8.lux
@@ -13,6 +13,7 @@
   (maybe.trusted (i64.sub 8)))
 
 (def: .public I8
+  Type
   (:by_example [size]
                (Sub size)
                ..sub