- Updated documentation for lux/cli, lux/compiler, lux/codata/*.

9 files changed, 110 insertions, 39 deletions

diff --git a/stdlib/source/lux.lux b/stdlib/source/lux.lux
index ac1289395..4ff962e0f 100644
--- a/stdlib/source/lux.lux
+++ b/stdlib/source/lux.lux
@@ -3485,10 +3485,10 @@
   (let [[exported? tokens'] (export-level^ tokens)
         ?parts (: (Maybe [AST (List AST) AST AST (List AST)])
                   (case tokens'
-                    (^ (list& [_ (#FormS (list& name args))] type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs))
+                    (^ (list& [_ (#FormS (list& name args))] [meta-rec-cursor (#;RecordS meta-rec-parts)] type defs))
                     (#Some name args type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs)
 
-                    (^ (list& name type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs))
+                    (^ (list& name [meta-rec-cursor (#;RecordS meta-rec-parts)] type defs))
                     (#Some name #Nil type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs)
 
                     (^ (list& [_ (#FormS (list& name args))] type defs))
diff --git a/stdlib/source/lux/cli.lux b/stdlib/source/lux/cli.lux
index 73c78a7a6..a8604180b 100644
--- a/stdlib/source/lux/cli.lux
+++ b/stdlib/source/lux/cli.lux
@@ -19,6 +19,7 @@
 
 ## [Types]
 (type: #export (CLI a)
+  {#;doc "A command-line interface parser."}
   (-> (List Text) (Error [(List Text) a])))
 
 ## [Utils]
@@ -126,6 +127,7 @@
       _     (#;Left (Text/append "Unknown parameters: " (text;join-with " " inputs))))))
 
 (def: #export (assert message test)
+  {#;doc "Fails with the given message if the test is false."}
   (-> Text Bool (CLI Unit))
   (lambda [inputs]
     (if test
@@ -166,6 +168,7 @@
       (#;Right [inputs' (sum;left l)]))))
 
 (def: #export (not opt)
+  {#;doc "The opposite of the given CLI."}
   (All [a] (-> (CLI a) (CLI Unit)))
   (lambda [inputs]
     (case (opt inputs)
diff --git a/stdlib/source/lux/codata/cont.lux b/stdlib/source/lux/codata/cont.lux
index a75e5a029..7f1b787e1 100644
--- a/stdlib/source/lux/codata/cont.lux
+++ b/stdlib/source/lux/codata/cont.lux
@@ -14,6 +14,7 @@
 
 ## [Types]
 (type: #export (Cont a)
+  {#;doc "Delimited continuations."}
   (All [b]
     (-> (-> a b) b)))
 
diff --git a/stdlib/source/lux/codata/env.lux b/stdlib/source/lux/codata/env.lux
index 818dd8a7e..18e07e84c 100644
--- a/stdlib/source/lux/codata/env.lux
+++ b/stdlib/source/lux/codata/env.lux
@@ -11,6 +11,7 @@
 
 ## [Types]
 (type: #export (Env r a)
+  {#;doc "Computations that have access to some environmental value."}
   (-> r a))
 
 ## [Structures]
@@ -38,7 +39,7 @@
 
 ## [Values]
 (def: #export ask
-  {#;doc "Get the value of the environment."}
+  {#;doc "Get the environment."}
   (All [r] (Env r r))
   (lambda [env] env))
 
@@ -52,6 +53,7 @@
   (env-proc env))
 
 (struct: #export (EnvT Monad<M>)
+  {#;doc "Monad transformer for Env."}
   (All [M] (-> (Monad M) (All [e] (Monad (All [a] (Env e (M a)))))))
   (def: applicative (compA Applicative<Env> (get@ #M;applicative Monad<M>)))
   (def: (join eMeMa)
@@ -61,5 +63,6 @@
         (run env eMa)))))
 
 (def: #export lift-env
+  {#;doc "Lift monadic values to the Env wrapper."}
   (All [M e a] (-> (M a) (Env e (M a))))
   (:: Monad<Env> wrap))
diff --git a/stdlib/source/lux/codata/function.lux b/stdlib/source/lux/codata/function.lux
index fba5528a8..4f13be813 100644
--- a/stdlib/source/lux/codata/function.lux
+++ b/stdlib/source/lux/codata/function.lux
@@ -8,11 +8,13 @@
   (lux (control monoid)))
 
 ## [Functions]
-(def: #export (const x y)
+(def: #export (const c)
+  {#;doc "Create constant functions."}
   (All [a b] (-> a (-> b a)))
-  x)
+  (lambda [_] c))
 
 (def: #export (flip f)
+  {#;doc "Flips the order of the arguments of a function."}
   (All [a b c]
     (-> (-> a b c) (-> b a c)))
   (lambda [x y] (f y x)))
diff --git a/stdlib/source/lux/codata/io.lux b/stdlib/source/lux/codata/io.lux
index 1398dfae5..e612c24c9 100644
--- a/stdlib/source/lux/codata/io.lux
+++ b/stdlib/source/lux/codata/io.lux
@@ -12,16 +12,16 @@
 
 ## [Types]
 (type: #export (IO a)
+  {#;doc "A type that represents synchronous, effectful computations that may interact with the outside world."}
   (-> Void a))
 
 ## [Syntax]
 (macro: #export (io tokens state)
-  {#;doc (doc
-           "Delays the evaluation of an expression, by wrapping it in an IO 'thunk'."
-           "Great for wrapping side-effecting computations (which won't be performed until the IO is \"run\")."
-           (io (exec
-                 (log! msg)
-                 "Some value...")))}
+  {#;doc (doc "Delays the evaluation of an expression, by wrapping it in an IO 'thunk'."
+              "Great for wrapping effectful computations (which won't be performed until the IO is \"run\")."
+              (io (exec
+                    (log! msg)
+                    "Some value...")))}
   (case tokens
     (^ (list value))
     (let [blank (: AST [["" -1 -1] (#;SymbolS ["" ""])])]
@@ -52,5 +52,6 @@
 
 ## [Functions]
 (def: #export (run action)
+  {#;doc "A way to execute IO computations and perform their side-effects."}
   (All [a] (-> (IO a) a))
   (action (:! Void [])))
diff --git a/stdlib/source/lux/codata/state.lux b/stdlib/source/lux/codata/state.lux
index 2ff0ea3a8..e0eebda56 100644
--- a/stdlib/source/lux/codata/state.lux
+++ b/stdlib/source/lux/codata/state.lux
@@ -11,6 +11,7 @@
 
 ## [Types]
 (type: #export (State s a)
+  {#;doc "Stateful computations."}
   (-> s [s a]))
 
 ## [Structures]
@@ -43,16 +44,19 @@
 
 ## [Values]
 (def: #export get
+  {#;doc "Read the current state."}
   (All [s] (State s s))
   (lambda [state]
     [state state]))
 
 (def: #export (put new-state)
+  {#;doc "Set the new state."}
   (All [s] (-> s (State s Unit)))
   (lambda [state]
     [new-state []]))
 
 (def: #export (update change)
+  {#;doc "Compute the new state."}
   (All [s] (-> (-> s s) (State s Unit)))
   (lambda [state]
     [(change state) []]))
@@ -71,6 +75,7 @@
       [state output])))
 
 (def: #export (run state action)
+  {#;doc "Run a stateful computation."}
   (All [s a] (-> s (State s a) [s a]))
   (action state))
 
@@ -98,13 +103,16 @@
         (wrap [state (f a)])))))
 
 (type: #export (State' M s a)
+  {#;doc "Stateful computations decorated by a monad."}
   (-> s (M [s a])))
 
 (def: #export (run' state action)
+  {#;doc "Run a stateful computation decorated by a monad."}
   (All [M s a] (-> s (State' M s a) (M [s a])))
   (action state))
 
 (struct: #export (StateT Monad<M>)
+  {#;doc "A monad transformer to create composite stateful computations."}
   (All [M s] (-> (Monad M) (Monad (State' M s))))
   (def: applicative (Applicative<StateT> Monad<M>))
   (def: (join sMsMa)
@@ -114,7 +122,8 @@
         (sMa state')))))
 
 (def: #export (lift-state Monad<M> ma)
-  (All [M s a] (-> (Monad M) (M a) (-> s (M [s a]))))
+  {#;doc "Lift monadic values to the State' wrapper."}
+  (All [M s a] (-> (Monad M) (M a) (State' M s a)))
   (lambda [state]
     (do Monad<M>
       [a ma]
diff --git a/stdlib/source/lux/codata/struct/stream.lux b/stdlib/source/lux/codata/struct/stream.lux
index 6eb0ed4a9..5691b0c69 100644
--- a/stdlib/source/lux/codata/struct/stream.lux
+++ b/stdlib/source/lux/codata/struct/stream.lux
@@ -16,6 +16,7 @@
 
 ## [Types]
 (type: #export (Stream a)
+  {#;doc "An infinite stream of lazily-evaluated values."}
   (Cont [a (Stream a)]))
 
 ## [Utils]
@@ -28,16 +29,21 @@
 
 ## [Functions]
 (def: #export (iterate f x)
+  {#;doc "Create a stream by applying a function to a value, and to its result, on and on..."}
   (All [a]
     (-> (-> a a) a (Stream a)))
   (@lazy [x (iterate f (f x))]))
 
 (def: #export (repeat x)
+  {#;doc "Repeat a value forever."}
   (All [a]
     (-> a (Stream a)))
   (@lazy [x (repeat x)]))
 
 (def: #export (cycle xs)
+  {#;doc "Go over the elements of a list forever.
+
+          The list shouldn't be empty."}
   (All [a]
     (-> (List a) (Maybe (Stream a))))
   (case xs
@@ -91,6 +97,7 @@
   )
 
 (def: #export (unfold step init)
+  {#;doc "A stateful way of infinitely calculating the values of a stream."}
   (All [a b]
     (-> (-> a [a b]) a (Stream b)))
   (let [[next x] (step init)]
@@ -104,6 +111,11 @@
       (filter p xs'))))
 
 (def: #export (partition p xs)
+  {#;doc "Split a stream in two based on a predicate.
+
+          The left side contains all entries for which the predicate is true.
+
+          The right side contains all entries for which the predicate is false."}
   (All [a] (-> (-> a Bool) (Stream a) [(Stream a) (Stream a)]))
   [(filter p xs) (filter (complement p) xs)])
 
diff --git a/stdlib/source/lux/compiler.lux b/stdlib/source/lux/compiler.lux
index feade4a8c..2f3fdbe3c 100644
--- a/stdlib/source/lux/compiler.lux
+++ b/stdlib/source/lux/compiler.lux
@@ -89,6 +89,7 @@
     (#;Right output)))
 
 (def: #export (either left right)
+  {#;doc "Pick whichever computation succeeds."}
   (All [a] (-> (Lux a) (Lux a) (Lux a)))
   (lambda [compiler]
     (case (left compiler)
@@ -99,6 +100,7 @@
       (#;Right [compiler' output]))))
 
 (def: #export (assert message test)
+  {#;doc "Fails with the given message if the test is false."}
   (-> Text Bool (Lux Unit))
   (lambda [compiler]
     (if test
@@ -106,6 +108,7 @@
       (#;Left message))))
 
 (def: #export (fail msg)
+  {#;doc "Fails with the given message."}
   (All [a]
     (-> Text (Lux a)))
   (lambda [_]
@@ -143,23 +146,24 @@
     [this-module-name current-module-name]
     (find-module this-module-name)))
 
-(def: #export (get-ann tag meta)
+(def: #export (get-ann tag anns)
+  {#;doc "Looks-up a particular annotation's value within the set of annotations."}
   (-> Ident Anns (Maybe Ann-Value))
   (let [[p n] tag]
-    (case meta
-      (#;Cons [[p' n'] dmv] meta')
+    (case anns
+      (#;Cons [[p' n'] dmv] anns')
       (if (and (Text/= p p')
                (Text/= n n'))
         (#;Some dmv)
-        (get-ann tag meta'))
+        (get-ann tag anns'))
       
       #;Nil
       #;None)))
 
 (do-template [<name> <tag> <type>]
-  [(def: #export (<name> tag meta)
+  [(def: #export (<name> tag anns)
      (-> Ident Anns (Maybe <type>))
-     (case (get-ann tag meta)
+     (case (get-ann tag anns)
        (#;Some (<tag> value))
        (#;Some value)
 
@@ -176,31 +180,34 @@
   [get-dict-ann  #;DictM  (List [Text Ann-Value])]
   )
 
-(def: #export (get-doc meta)
+(def: #export (get-doc anns)
+  {#;doc "Looks-up a definition's documentation."}
   (-> Anns (Maybe Text))
-  (get-text-ann ["lux" "doc"] meta))
+  (get-text-ann ["lux" "doc"] anns))
 
-(def: #export (flag-set? flag-name meta)
+(def: #export (flag-set? flag-name anns)
+  {#;doc "Finds out whether an annotation-as-a-flag is set (has value 'true')."}
   (-> Ident Anns Bool)
-  (case (get-ann flag-name meta)
+  (case (get-ann flag-name anns)
     (#;Some (#;BoolM true))
     true
 
     _
     false))
 
-(do-template [<name> <tag>]
+(do-template [<name> <tag> <desc>]
   [(def: #export <name>
+     {#;doc (#;TextM ($_ Text/append "Checks whether a definition is " <desc> "."))}
      (-> Anns Bool)
      (flag-set? (ident-for <tag>)))]
 
-  [export?   #;export?]
-  [hidden?   #;hidden?]
-  [macro?    #;macro?]
-  [type?     #;type?]
-  [struct?   #;struct?]
-  [type-rec? #;type-rec?]
-  [sig?      #;sig?]
+  [export?   #;export?   "exported"]
+  [hidden?   #;hidden?   "hidden"]
+  [macro?    #;macro?    "a macro"]
+  [type?     #;type?     "a type"]
+  [struct?   #;struct?   "a structure"]
+  [type-rec? #;type-rec? "a recursive type"]
+  [sig?      #;sig?      "a signature"]
   )
 
 (do-template [<name> <tag> <type>]
@@ -217,17 +224,18 @@
   [try-mtext #;TextM Text]
   )
 
-(do-template [<name> <tag>]
-  [(def: #export (<name> meta)
+(do-template [<name> <tag> <desc>]
+  [(def: #export (<name> anns)
+     {#;doc (#;TextM ($_ Text/append "Looks up the arguments of a " <desc> "."))}
      (-> Anns (List Text))
      (default (list)
        (do Monad<Maybe>
-         [_args (get-ann (ident-for <tag>) meta)
+         [_args (get-ann (ident-for <tag>) anns)
           args (try-mlist _args)]
          (mapM @ try-mtext args))))]
 
-  [func-args #;func-args]
-  [type-args #;type-args]
+  [func-args #;func-args "function"]
+  [type-args #;type-args "parameterized type"]
   )
 
 (def: (find-macro' modules this-module module name)
@@ -256,6 +264,9 @@
            (#;Right [state (find-macro' (get@ #;modules state) this-module module name)]))))))
 
 (def: #export (normalize ident)
+  {#;doc "If given an identifier without a module prefix, gives it the current module's name as prefix.
+
+          Otherwise, returns the identifier as-is."}
   (-> Ident (Lux Ident))
   (case ident
     ["" name]
@@ -267,6 +278,9 @@
     (:: Monad<Lux> wrap ident)))
 
 (def: #export (macro-expand-once syntax)
+  {#;doc "Given code that requires applying a macro, does it once and returns the result.
+
+          Otherwise, returns the code as-is."}
   (-> AST (Lux (List AST)))
   (case syntax
     [_ (#;FormS (#;Cons [[_ (#;SymbolS macro-name)] args]))]
@@ -284,6 +298,9 @@
     (:: Monad<Lux> wrap (list syntax))))
 
 (def: #export (macro-expand syntax)
+  {#;doc "Given code that requires applying a macro, expands repeatedly until no more direct macro-calls are left.
+
+          Otherwise, returns the code as-is."}
   (-> AST (Lux (List AST)))
   (case syntax
     [_ (#;FormS (#;Cons [[_ (#;SymbolS macro-name)] args]))]
@@ -304,6 +321,7 @@
     (:: Monad<Lux> wrap (list syntax))))
 
 (def: #export (macro-expand-all syntax)
+  {#;doc "Expands all macro-calls everywhere recursively, until only primitive/base code remains."}
   (-> AST (Lux (List AST)))
   (case syntax
     [_ (#;FormS (#;Cons [[_ (#;SymbolS macro-name)] args]))]
@@ -337,6 +355,9 @@
     (:: Monad<Lux> wrap (list syntax))))
 
 (def: #export (gensym prefix)
+  {#;doc "Generates a unique identifier as an AST node (ready to be used in code templates).
+
+          A prefix can be given (or just be empty text \"\") to better identify the code for debugging purposes."}
   (-> Text (Lux AST))
   (lambda [state]
     (#;Right [(update@ #;seed n.inc state)
@@ -376,6 +397,7 @@
     (fail "Wrong syntax for with-gensyms")))
 
 (def: #export (macro-expand-1 token)
+  {#;doc "Works just like macro-expand, except that it ensures that the output is a single AST token."}
   (-> AST (Lux AST))
   (do Monad<Lux>
     [token+ (macro-expand token)]
@@ -404,6 +426,7 @@
     (#;Some y) (#;Some y)))
 
 (def: #export (find-var-type name)
+  {#;doc "Looks-up the type of a local variable somewhere in the environment."}
   (-> Text (Lux Type))
   (lambda [state]
     (let [test (: (-> [Text Analysis] Bool)
@@ -424,6 +447,7 @@
         (#;Left ($_ Text/append "Unknown variable: " name))))))
 
 (def: #export (find-def name)
+  {#;doc "Looks-up a definition's whole data in the available modules (including the current one)."}
   (-> Ident (Lux Def))
   (lambda [state]
     (case (: (Maybe Def)
@@ -431,19 +455,21 @@
                [#let [[v-prefix v-name] name]
                 (^slots [#;defs]) (get v-prefix (get@ #;modules state))]
                (get v-name defs)))
-      (#;Some _meta)
-      (#;Right [state _meta])
+      (#;Some _anns)
+      (#;Right [state _anns])
 
       _
       (#;Left ($_ Text/append "Unknown definition: " (Ident/encode name))))))
 
 (def: #export (find-def-type name)
+  {#;doc "Looks-up a definition's type in the available modules (including the current one)."}
   (-> Ident (Lux Type))
   (do Monad<Lux>
     [[def-type def-data def-value] (find-def name)]
     (wrap def-type)))
 
 (def: #export (find-type name)
+  {#;doc "Looks-up the type of either a local variable or a definition."}
   (-> Ident (Lux Type))
   (do Monad<Lux>
     [#let [[_ _name] name]]
@@ -453,12 +479,14 @@
               (find-def-type name)))))
 
 (def: #export (find-type-def name)
+  {#;doc "Finds the value of a type definition (such as Int, Top or Compiler)."}
   (-> Ident (Lux Type))
   (do Monad<Lux>
     [[def-type def-data def-value] (find-def name)]
     (wrap (:! Type def-value))))
 
 (def: #export (defs module-name)
+  {#;doc "The entire list of definitions in a module (including the unexported/private ones)."}
   (-> Text (Lux (List [Text Def])))
   (lambda [state]
     (case (get module-name (get@ #;modules state))
@@ -467,6 +495,7 @@
       )))
 
 (def: #export (exports module-name)
+  {#;doc "All the exported definitions in a module."}
   (-> Text (Lux (List [Text Def])))
   (do Monad<Lux>
     [defs (defs module-name)]
@@ -476,6 +505,7 @@
                   defs))))
 
 (def: #export modules
+  {#;doc "All the available modules (including the current one)."}
   (Lux (List Text))
   (lambda [state]
     (|> state
@@ -485,6 +515,7 @@
         #;Right)))
 
 (def: #export (tags-of type-name)
+  {#;doc "All the tags associated with a type definition."}
   (-> Ident (Lux (List Ident)))
   (do Monad<Lux>
     [#let [[module name] type-name]
@@ -497,11 +528,13 @@
       (wrap (list)))))
 
 (def: #export cursor
+  {#;doc "The cursor of the current expression being analyzed."}
   (Lux Cursor)
   (lambda [state]
     (#;Right [state (get@ #;cursor state)])))
 
 (def: #export expected-type
+  {#;doc "The expected type of the current expression being analyzed."}
   (Lux Type)
   (lambda [state]
     (case (get@ #;expected state)
@@ -512,15 +545,18 @@
       (#;Left "Not expecting any type."))))
 
 (def: #export (imported-modules module-name)
+  {#;doc "All the modules imported by a specified module."}
   (-> Text (Lux (List Text)))
   (do Monad<Lux>
     [(^slots [#;imports]) (find-module module-name)]
     (wrap imports)))
 
-(def: #export (resolve-tag (^@ tag [module name]))
+(def: #export (resolve-tag tag)
+  {#;doc "Given a tag, finds out what is its index, its related tag-list and it's associated type."}
   (-> Ident (Lux [Nat (List Ident) Type]))
   (do Monad<Lux>
-    [=module (find-module module)
+    [#let [[module name] tag]
+     =module (find-module module)
      this-module-name current-module-name]
     (case (get name (get@ #;tags =module))
       (#;Some [idx tag-list exported? type])
@@ -533,6 +569,7 @@
       (fail ($_ Text/append "Unknown tag: " (Ident/encode tag))))))
 
 (def: #export (tag-lists module)
+  {#;doc "All the tag-lists defined in a module, with their associated types."}
   (-> Text (Lux (List [(List Ident) Type])))
   (do Monad<Lux>
     [=module (find-module module)
@@ -545,6 +582,7 @@
                           [tag-list type]))))))
 
 (def: #export locals
+  {#;doc "All the local variables currently in scope, separated in different scopes."}
   (Lux (List (List [Text Type])))
   (lambda [state]
     (case (list;inits (get@ #;scopes state))
@@ -559,6 +597,7 @@
                           scopes)]))))
 
 (def: #export (un-alias def-name)
+  {#;doc "Given an aliased definition's name, returns the original definition being referenced."}
   (-> Ident (Lux Ident))
   (do Monad<Lux>
     [def-name (normalize def-name)
@@ -571,6 +610,7 @@
       (wrap def-name))))
 
 (def: #export get-compiler
+  {#;doc "Obtains the current state of the compiler."}
   (Lux Compiler)
   (lambda [compiler]
     (#;Right [compiler compiler])))