--- loncom/interface/Attic/lonchart.pm	2002/07/08 13:38:52	1.55
+++ loncom/interface/Attic/lonchart.pm	2002/07/08 14:50:25	1.56
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # (Publication Handler
 #
-# $Id: lonchart.pm,v 1.55 2002/07/08 13:38:52 stredwic Exp $
+# $Id: lonchart.pm,v 1.56 2002/07/08 14:50:25 stredwic Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -672,7 +672,7 @@ here in the future.
 
 =item &DownloadPrerequisiteData()
 
-Collects lastname, generation, middlename, firstname PID, and section for each
+Collects lastname, generation, middlename, firstname, PID, and section for each
 student from their environment database.  The list of students is built from
 collecting a classlist for the course that is to be displayed.
 
@@ -793,6 +793,28 @@ tie hash to database later.
 
 =pod
 
+=item &ProcessTopResourceMap()
+
+Trace through the "big hash" created in rat/lonuserstate.pm::loadmap.  
+Basically, this function organizes a subset of the data and stores it in
+cached data.  The data stored is the problems, sequences, sequence titles,
+parts of problems, and their ordering.  Column width information is also 
+partially handled here on a per sequence basis.
+
+=over 4
+
+Input: $ChartDB, $c
+
+$ChartDB:  The name of the cache database file
+
+$c:  The connection class used to determine if an abort has been sent to the 
+browser
+
+Output: A string that contains an error message or "OK" if everything went 
+smoothly.
+
+=back
+
 =cut
 
 sub ProcessTopResourceMap {
@@ -981,6 +1003,35 @@ sub ProcessTopResourceMap {
     return 'OK';
 }
 
+=pod
+
+=item &ProcessSection()
+
+Determine the section number for a student for the class.  A student can have 
+multiple sections for the same class.  The correct one is chosen.
+
+=over 4
+
+Input: $sectionData, $courseid, $ActiveFlag
+
+$sectionData:  A pointer to a hash containing all section data for this 
+student for the class
+
+$courseid:  The course ID.
+
+$ActiveFlag:  The student's active status (Active/Expired)
+
+Output: $oldsection, $cursection, or -1
+
+$oldsection and $cursection and sections number that will be displayed in the 
+chart.
+
+-1 is returned if an error occurs.
+
+=back
+
+=cut
+
 sub ProcessSection {
     my ($sectionData, $courseid,$ActiveFlag)=@_;
     $courseid=~s/\_/\//g;
@@ -1035,8 +1086,44 @@ sub ProcessSection {
     return '-1';
 }
 
+=pod
+
+=item &ProcessStudentInformation()
+
+Takes data downloaded for a student and breaks it up into managable pieces and 
+stored in cache data.  The username, domain, class related date, PID, 
+full name, and section are all processed here.
+
+=over 4
+
+Input: $CacheData, $studentInformation, $section, $date, $name, $courseID
+
+$CacheData:  A hash pointer to the cached data
+
+$studentInformation:  Student information is what was requested in 
+&DownloadPrerequistedData().  See that function for what data is requested.
+
+$section: A hash pointer to class section related information.
+
+$date:  A composite of the start and end date for this class for this
+student.  Format:  end:start
+
+$name:  the username:domain information
+
+$courseID: The course ID
+
+Output: None
+
+*NOTE:  There is no return value, but if an error occurs a key is added to 
+the cache data with the value being the error message.  The key is 
+username:domain:error.  It will only exist if an error occurs.
+
+=back
+
+=cut
+
 sub ProcessStudentInformation {
-    my ($CacheData,$studentInformation,$section,$date,$name,$courseID,$c)=@_;
+    my ($CacheData,$studentInformation,$section,$date,$name,$courseID)=@_;
     my ($studentName,$studentDomain) = split(/\:/,$name);
 
     $CacheData->{$name.':username'}=$studentName;
@@ -1066,9 +1153,43 @@ sub ProcessStudentInformation {
 	$CacheData->{$name.':section'}='';
     }
 
-    return 0;
+    return;
 }
 
+=pod
+
+=item &ProcessClassList()
+
+Taking the class list dumped from &DownloadPrerequisiteData(), all the 
+students and their non-class information is processed using the 
+&ProcessStudentInformation() function.  A date stamp is also recorded for
+when the data was processed.
+
+=over 4
+
+Input: $classlist, $courseID, $ChartDB, $c
+
+$classlist:  The hash of data collected about a student from 
+&DownloadPrerequisteData().  The hash contains a list of students, a pointer 
+to a hash of student information for each student, and each student's section 
+number.
+
+$courseID:  The course ID
+
+$ChartDB:  The name of the cache database file.
+
+$c:  The connection class used to determine if an abort has been sent to the 
+browser
+
+Output: @names
+
+@names:  An array of students whose information has been processed, and are to 
+be considered in an arbitrary order.
+
+=back
+
+=cut
+
 sub ProcessClassList {
     my ($classlist,$courseID,$ChartDB,$c)=@_;
     my @names=();
@@ -1089,7 +1210,7 @@ sub ProcessClassList {
                                     $classlist->{$name.':studentInformation'},
                                     $classlist->{$name.':section'},
                                     $classlist->{$name},
-                                    $name,$courseID,$c);
+                                    $name,$courseID);
         }
 
         # Time of download
@@ -1100,6 +1221,40 @@ sub ProcessClassList {
     return @names;
 }
 
+=pod
+
+=item &ProcessStudentData()
+
+Takes the course data downloaded for a student in 
+&DownloadStudentCourseInformation() and breaks it up into key value pairs
+to be stored in the cached data.  The keys are comprised of the 
+$username:$domain:$keyFromCourseDatabase.  The student username:domain is
+stored away signifying that the student's information has been downloaded and 
+can be reused from cached data.
+
+=over 4
+
+Input: $courseData, $name, $ChartDB
+
+$courseData:  A hash pointer that points to the course data downloaded for a 
+student.
+
+$name:  username:domain
+
+$ChartDB:  The name of the cache database file which will allow the data to
+be written to the cache.
+
+Output: None
+
+*NOTE:  There is no output, but an error message is stored away in the cache 
+data.  This is checked in &FormatStudentData().  The key username:domain:error 
+will only exist if an error occured.  The error is an error from 
+&DownloadStudentCourseInformation().
+
+=back
+
+=cut
+
 sub ProcessStudentData {
     my ($courseData, $name, $ChartDB)=@_;