--- loncom/interface/createaccount.pm	2012/05/16 21:19:39	1.48
+++ loncom/interface/createaccount.pm	2012/05/17 18:05:42	1.50
@@ -3,7 +3,7 @@
 # institutional log-in ID (institutional authentication required - localauth
 #  or kerberos) or an e-mail address.
 #
-# $Id: createaccount.pm,v 1.48 2012/05/16 21:19:39 droeschl Exp $
+# $Id: createaccount.pm,v 1.50 2012/05/17 18:05:42 www Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -683,7 +683,11 @@ sub start_session {
     return;
 }
 
-
+#
+# The screen that the user gets to create his or her account
+# Desired username, desired password, etc
+# Stores token to store DES-key and stage during creation session
+#
 sub print_dataentry_form {
     my ($r,$domain,$lonhost,$include,$mailtoken,$now,$username,$start_page) = @_;
     my ($error,$output);
@@ -763,6 +767,10 @@ ENDSERVERFORM
     return $output;
 }
 
+#
+# Retrieve rules for generating accounts from domain configuration
+# Can the user make a new account or just self-enroll?
+
 sub get_creation_controls {
     my ($domain,$usercreation) = @_;
     my (@cancreate,@statustocreate);
@@ -802,8 +810,12 @@ sub get_creation_controls {
 
 sub create_account {
     my ($r,$domain,$lonhost,$username,$domdesc) = @_;
+# Get the token info
     my ($retrieved,$output,$upass) = &process_credentials($env{'form.logtoken'},
                                                           $env{'form.serverid'}); 
+# $retrieved is 'ok' if things worked
+# $output is user error output
+# $upass is the decrypted password
     # Error messages
     my $error     = '<span class="LC_error">'.&mt('Error:').' ';
     my $end       = '</span><br /><br />';
@@ -812,6 +824,7 @@ sub create_account {
                     &Apache::loncommon::end_page();
     if ($retrieved eq 'ok') {
         if ($env{'form.courseid'} ne '') {
+# See if we are allowed to use this username per domain rules (number of characters, etc)
             my ($result,$userchkmsg) = &check_id($username,$domain,$domdesc);
             if ($result eq 'fail') {
                 $output = $error.&mt('Invalid ID format').$end.
@@ -822,13 +835,17 @@ sub create_account {
     } else {
         return ('fail',$error.$output.$end.$rtnlink);
     }
-    # Call modifyuser
+    # Yes! We can do this. Valid token, valid username format
+    # Create an internally authenticated account with password $upass 
+    # if the account does not exist yet
+    # Assign student/staff number $env{'form.cid'}, first name, last name, etc
     my $result = 
         &Apache::lonnet::modifyuser($domain,$username,$env{'form.cid'},
                                     'internal',$upass,$env{'form.cfirstname'},
                                     $env{'form.cmiddlename'},$env{'form.clastname'},
                                     $env{'form.cgeneration'},undef,undef,$username);
     $output = &mt('Generating user: [_1]',$result);
+    # Now that the user exists, we can have a homeserver
     my $uhome = &Apache::lonnet::homeserver($username,$domain);
     $output .= '<br />'.&mt('Home server: [_1]',$uhome).' '.
               &Apache::lonnet::hostname($uhome).'<br /><br />';
@@ -838,6 +855,12 @@ sub create_account {
 sub username_validation {
     my ($r,$username,$domain,$domdesc,$contact_name,$contact_email,$courseid,
         $lonhost,$statustocreate) = @_;
+# $username,$domain: for the user who needs to be validated
+# $domdesc: full name of the domain (for error messages)
+# $contact_name, $contact_email: name and email for user assistance (for error messages in &username_check
+# $courseid: ID of the course that the user should be validated for, goes into start_session
+# $statustocreate: -> inststatus in username_check ('faculty', 'staff', 'student', ...)
+ 
     my ($retrieved,$output,$upass);
 
     $username= &LONCAPA::clean_username($username);
@@ -1092,6 +1115,9 @@ sub username_activation {
 sub check_id {
     my ($username,$domain,$domdesc) = @_;
     # Check ID format
+    # Is $username in an okay format for $domain 
+    # (right number of characters, special characters, etc - follow domain rules)?
+    # $domdesc is just used for user error messages
     my (%alerts,%rulematch,%inst_results,%curr_rules,%checkhash);
     my %checks = ('id' => 1);
     %{$checkhash{$username.':'.$domain}} = (
@@ -1230,6 +1256,12 @@ ENDSERVERFORM
 }
 
 sub process_credentials {
+#
+# Fetches the information from the logtoken via tmpget
+# Token contains the DES-key and the stage of the process (would only be "createaccount")
+# $lonhost in this routine is *not* necessarily the machine that this runs on,
+# but $env{'form.serverid'}, the machine that issued the token. 
+#
     my ($logtoken,$lonhost) = @_;
     my $tmpinfo=Apache::lonnet::reply('tmpget:'.$logtoken,$lonhost);
     my ($retrieved,$output,$upass);
@@ -1251,6 +1283,10 @@ sub process_credentials {
     } else {
         $output = &mt('Unable to retrieve your log-in information - unexpected context');
     }
+# $retrieved is 'ok' if retrieved okay
+# $output is screen output for the user
+# $upass is $env{'form.upass'}, decrypted with the DES-key, if stage was 'createaccount'
+
     return ($retrieved,$output,$upass);
 }