# HG changeset patch
# User Robin Green <greenrd@greenrd.org>
# Date 1309258557 -3600
# Node ID aa0c6382aa5749804bafdd2a866a676b76e06fc4
# Parent  f561025bb68e3b0eec5ee2c8bfddaee17dad7cf9
top.urs: More comments

diff -r f561025bb68e -r aa0c6382aa57 lib/ur/top.urs
--- a/lib/ur/top.urs	Sun Jun 26 19:45:21 2011 -0400
+++ b/lib/ur/top.urs	Tue Jun 28 11:55:57 2011 +0100
@@ -21,21 +21,34 @@
 
 val not : bool -> bool
 
+(* Type-level identity function *)
 con id = K ==> fn t :: K => t
+
+(* Type-level function which yields the value-level record
+   described by the given type-level record *)
 con record = fn t :: {Type} => $t
+
 con fst = K1 ==> K2 ==> fn t :: (K1 * K2) => t.1
 con snd = K1 ==> K2 ==> fn t :: (K1 * K2) => t.2
 con fst3 = K1 ==> K2 ==> K3 ==> fn t :: (K1 * K2 * K3) => t.1
 con snd3 = K1 ==> K2 ==> K3 ==> fn t :: (K1 * K2 * K3) => t.2
 con thd3 = K1 ==> K2 ==> K3 ==> fn t :: (K1 * K2 * K3) => t.3
 
+(* Convert a record of n Units into a type-level record where
+   each field has the same value (which describes a uniformly
+   typed record) *)
 con mapU = K ==> fn f :: K => map (fn _ :: Unit => f)
 
+(* Existential type former *)
 con ex :: K --> (K -> Type) -> Type
 
+(* Introduction of existential type *)
 val ex_intro : K --> tf :: (K -> Type) -> choice :: K -> tf choice -> ex tf
+
+(* Eliminator for existential type *)
 val ex_elim : K --> tf ::: (K -> Type) -> ex tf -> res ::: Type -> (choice :: K -> tf choice -> res) -> res
 
+(* Composition of ordinary (value-level) functions *)
 val compose : t1 ::: Type -> t2 ::: Type -> t3 ::: Type
               -> (t2 -> t3) -> (t1 -> t2) -> (t1 -> t3)
 
@@ -45,37 +58,52 @@
 val txt : t ::: Type -> ctx ::: {Unit} -> use ::: {Type} -> show t -> t
           -> xml ctx use []
 
+(* Given a polymorphic type (tf) and a means of constructing
+   "default" values of tf applied to arbitrary arguments,
+   constructs records consisting of those "default" values *)
 val map0 : K --> tf :: (K -> Type)
            -> (t :: K -> tf t)
            -> r ::: {K} -> folder r -> $(map tf r)
+
+(* Given two polymorphic types (tf1 and tf2) and a means of
+   converting from tf1 t to tf2 t for arbitrary t,
+   converts records of tf1's to records of tf2's *)
 val mp : K --> tf1 :: (K -> Type) -> tf2 :: (K -> Type)
          -> (t ::: K -> tf1 t -> tf2 t)
          -> r ::: {K} -> folder r -> $(map tf1 r) -> $(map tf2 r)
+
+(* Two-argument conversion form of mp *)
 val map2 : K --> tf1 :: (K -> Type) -> tf2 :: (K -> Type) -> tf :: (K -> Type)
            -> (t ::: K -> tf1 t -> tf2 t -> tf t)
            -> r ::: {K} -> folder r -> $(map tf1 r) -> $(map tf2 r) -> $(map tf r)
+
+(* Three-argument conversion form of mp *)
 val map3 : K --> tf1 :: (K -> Type) -> tf2 :: (K -> Type) -> tf3 :: (K -> Type) -> tf :: (K -> Type)
            -> (t ::: K -> tf1 t -> tf2 t -> tf3 t -> tf t)
            -> r ::: {K} -> folder r -> $(map tf1 r) -> $(map tf2 r) -> $(map tf3 r) -> $(map tf r)
 
+(* Fold along a uniformly (homogenously) typed record *)
 val foldUR : tf :: Type -> tr :: ({Unit} -> Type)
              -> (nm :: Name -> rest :: {Unit}
                  -> [[nm] ~ rest] =>
                        tf -> tr rest -> tr ([nm] ++ rest))
              -> tr [] -> r ::: {Unit} -> folder r -> $(mapU tf r) -> tr r
 
+(* Fold (generalized safe zip) along two equal-length uniformly-typed records *)
 val foldUR2 : tf1 :: Type -> tf2 :: Type -> tr :: ({Unit} -> Type)
              -> (nm :: Name -> rest :: {Unit}
                  -> [[nm] ~ rest] =>
                        tf1 -> tf2 -> tr rest -> tr ([nm] ++ rest))
              -> tr [] -> r ::: {Unit} -> folder r -> $(mapU tf1 r) -> $(mapU tf2 r) -> tr r
 
+(* Fold along a heterogenously-typed record *)
 val foldR : K --> tf :: (K -> Type) -> tr :: ({K} -> Type)
              -> (nm :: Name -> t :: K -> rest :: {K}
                  -> [[nm] ~ rest] =>
                        tf t -> tr rest -> tr ([nm = t] ++ rest))
              -> tr [] -> r ::: {K} -> folder r -> $(map tf r) -> tr r
 
+(* Fold (generalized safe zip) along two heterogenously-typed records *)
 val foldR2 : K --> tf1 :: (K -> Type) -> tf2 :: (K -> Type)
              -> tr :: ({K} -> Type)
              -> (nm :: Name -> t :: K -> rest :: {K}
@@ -84,6 +112,7 @@
              -> tr []
              -> r ::: {K} -> folder r -> $(map tf1 r) -> $(map tf2 r) -> tr r
 
+(* Fold (generalized safe zip) along three heterogenously-typed records *)
 val foldR3 : K --> tf1 :: (K -> Type) -> tf2 :: (K -> Type) -> tf3 :: (K -> Type)
              -> tr :: ({K} -> Type)
              -> (nm :: Name -> t :: K -> rest :: {K}
@@ -92,11 +121,13 @@
              -> tr []
              -> r ::: {K} -> folder r -> $(map tf1 r) -> $(map tf2 r) -> $(map tf3 r) -> tr r
 
+(* Generate some XML by mapping over a uniformly-typed record *)
 val mapUX : tf :: Type -> ctx :: {Unit}
             -> (nm :: Name -> rest :: {Unit} -> [[nm] ~ rest] =>
                 tf -> xml ctx [] [])
             -> r ::: {Unit} -> folder r -> $(mapU tf r) -> xml ctx [] []
 
+(* Generate some XML by mapping over a heterogenously-typed record *)
 val mapX : K --> tf :: (K -> Type) -> ctx :: {Unit}
            -> (nm :: Name -> t :: K -> rest :: {K}
                -> [[nm] ~ rest] =>