# HG changeset patch
# User Adam Chlipala <adam@chlipala.net>
# Date 1294345035 18000
# Node ID dd8eb53da51b11f5eac6ecd0e4ac3caeb1543f18
# Parent  df2eb629f21a0dda56e780eb03cd27b92097c42f
Pretend user isn't logged in when he gives bogus session data; add some documentation to openidUser.urs

diff -r df2eb629f21a -r dd8eb53da51b src/ur/openidUser.ur
--- a/src/ur/openidUser.ur	Thu Jan 06 14:42:37 2011 -0500
+++ b/src/ur/openidUser.ur	Thu Jan 06 15:17:15 2011 -0500
@@ -54,7 +54,7 @@
                                     WHERE session.Id = {[login.Session]}
                                       AND session.Key = {[login.Key]});
             case ident of
-                None => error <xml>Invalid or expired session</xml>
+                None => return None
               | Some None => return None
               | Some (Some ident) =>
                 valid <- oneRowE1 (SELECT COUNT( * ) > 0
diff -r df2eb629f21a -r dd8eb53da51b src/ur/openidUser.urs
--- a/src/ur/openidUser.urs	Thu Jan 06 14:42:37 2011 -0500
+++ b/src/ur/openidUser.urs	Thu Jan 06 15:17:15 2011 -0500
@@ -1,16 +1,40 @@
+(* This module provides generic user authentication functionality, backed by
+ * OpenID authentication.  Each account (named with a short alphanumeric string)
+ * is associated with one or more OpenID identifiers, any of which may be used
+ * to log in as that user.  This module provides all the code you need to sign
+ * users up, log them in, and check which user is logged in.
+ *
+ * Module author: Adam Chlipala
+ *)
+
+(* Instantiate this functor to create your customized authentication scheme. *)
 functor Make(M: sig
                  con cols :: {Type}
                  constraint [Id] ~ cols
                  val folder : folder cols
                  val inj : $(map sql_injectable cols)
-                 (* Extra columns to add to the user database table *)
+                 (* Extra columns of profile information to include in the user
+                  * database table *)
 
                  type creationState
+                 (* The type of client-side state used while soliciting sign-up
+                  * input *)
                  type creationData
+                 (* A functional representation of the latest client-side state *)
+
                  val creationState : transaction creationState
+                 (* Create some fresh client-side state. *)
+
                  val render : creationState -> xtable
+                 (* Display widgets. *)
+
                  val tabulate : creationState -> signal creationData
-                 val choose : sql_table ([Id = string] ++ cols) [Pkey = [Id]] -> creationData -> transaction $cols
+                 (* Functionalize current state. *)
+
+                 val choose : sql_table ([Id = string] ++ cols) [Pkey = [Id]]
+                              -> creationData -> transaction $cols
+                 (* Use functionalized state to choose initial column values,
+                  * given a handle to the users table. *)
 
                  val sessionLifetime : int
                  (* Number of seconds a session may live *)
@@ -19,27 +43,36 @@
                  (* Where to send the user after he logs out *)
 
                  val secureCookies : bool
-                 (* Should authentication cookies be restricted to SSL connections? *)
+                 (* Should authentication cookies be restricted to SSL
+                  * connections? *)
 
                  val association : Openid.association_mode
                  (* OpenID cryptography preferences *)
 
                  val realm : option string
-                 (* See end of [Openid] module's documentation for the meaning of realms *)
+                 (* See end of [Openid] module's documentation for the meaning
+                  * of realms. *)
 
                  val formClass : css_class
+                 (* CSS class for <table>, <th>, and <td> elements used in
+                  * sign-up form *)
              end) : sig
 
     type user
     val show_user : show user
     val inj_user : sql_injectable_prim user
+    (* The abstract type of user IDs.  It's really [string], but this is only
+     * exposed via some standard type class instances. *)
 
     table user : ([Id = user] ++ M.cols)
       PRIMARY KEY Id
 
     val current : transaction (option user)
+    (* Figure out which, if any, user is logged in on this connection. *)
 
     val main : (string -> xbody -> transaction page) -> transaction xbody
-    (* Pass in your generic page template; get out the HTML snippet for user management *)
+    (* Pass in your generic page template; get out the HTML snippet for user
+     * management, suitable for, e.g., inclusion in your standard page
+     * header. *)
 
 end