[LON-CAPA-cvs] cvs: loncom /enrollment localenroll.pm /homework inputtags.pm lonhomework.pm randomlabel.pm response.pm structuretags.pm

jms lon-capa-cvs-allow@mail.lon-capa.org
Tue, 25 Nov 2008 13:16:27 -0000


This is a MIME encoded message

--jms1227618987
Content-Type: text/plain

jms		Tue Nov 25 13:16:27 2008 EDT

  Modified files:              
    /loncom/homework	inputtags.pm randomlabel.pm response.pm 
                    	lonhomework.pm structuretags.pm 
    /loncom/enrollment	localenroll.pm 
  Log:
  POD documentation changes
  
--jms1227618987
Content-Type: text/plain
Content-Disposition: attachment; filename="jms-20081125131627.txt"

Index: loncom/homework/inputtags.pm
diff -u loncom/homework/inputtags.pm:1.248 loncom/homework/inputtags.pm:1.249
--- loncom/homework/inputtags.pm:1.248	Sun Nov 16 02:46:25 2008
+++ loncom/homework/inputtags.pm	Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # input  definitons
 #
-# $Id: inputtags.pm,v 1.248 2008/11/16 02:46:25 raeburn Exp $
+# $Id: inputtags.pm,v 1.249 2008/11/25 13:16:17 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -25,6 +25,30 @@
 #
 # http://www.lon-capa.org/
 
+=pod
+
+=head1 NAME
+
+Apache::inputtags
+
+=head1 SYNOPSIS
+
+
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item 
+
+=back
+
+=cut
+
 package Apache::inputtags;
 use HTML::Entities();
 use strict;
@@ -38,41 +62,47 @@
     &Apache::lonxml::register('Apache::inputtags',('hiddenline','textfield','textline'));
 }
 
-#   Initializes a set of global variables used during the parse of the problem.
-#
-#  @Apache::inputtags::input        - List of current input ids.
-#  @Apache::inputtags::inputlist    - List of all input ids seen this problem.
-#  @Apache::inputtags::response     - List of all current resopnse ids.
-#  @Apache::inputtags::responselist - List of all response ids seen this 
-#                                       problem.
-#  @Apache::inputtags::hint         - List of all hint ids.
-#  @Apache::inputtags::hintlist     - List of all hint ids seen this problem.
-#  @Apache::inputtags::previous     - List describing if specific responseds
-#                                       have been used
-#  @Apache::inputtags::previous_version - Submission responses were used in.
-#  $Apache::inputtags::part         - Current part id (valid only in 
-#                                       <problem>)
-#                                     0 if not in a part.
-#  @Apache::inputtags::partlist     - List of part ids seen in the current
-#                                       <problem>
-#  @Apache::inputtags::status       - List of problem  statuses. First 
-#                                     element is the status of the <problem>
-#                                     the remainder are for individual <part>s.
-#  %Apache::inputtags::params       - Hash of defined parameters for the
-#                                     current response.
-#  @Apache::inputtags::import       - List of all ids for <import> thes get
-#                                     join()ed and prepended.
-#  @Apache::inputtags::importlist   - List of all import ids seen.
-#  $Apache::inputtags::response_with_no_part
-#                                   - Flag set true if we have seen a response
-#                                     that is not inside a <part>
-#  %Apache::inputtags::answertxt    - <*response> tags store correct
-#                                     answer strings for display by <textline/>
-#                                     in this hash.
-#  %Apache::inputtags::submission_display
-#                                   - <*response> tags store improved display
-#                                     of submission strings for display by part
-#                                     end.
+=pod
+
+=item initialize_inputtags()
+
+Initializes a set of global variables used during the parse of the problem.
+
+@Apache::inputtags::input        - List of current input ids.
+@Apache::inputtags::inputlist    - List of all input ids seen this problem.
+@Apache::inputtags::response     - List of all current resopnse ids.
+@Apache::inputtags::responselist - List of all response ids seen this 
+                                     problem.
+@Apache::inputtags::hint         - List of all hint ids.
+@Apache::inputtags::hintlist     - List of all hint ids seen this problem.
+@Apache::inputtags::previous     - List describing if specific responseds
+                                     have been used
+@Apache::inputtags::previous_version - Submission responses were used in.
+$Apache::inputtags::part         - Current part id (valid only in 
+                                     <problem>)
+                                   0 if not in a part.
+@Apache::inputtags::partlist     - List of part ids seen in the current
+                                     <problem>
+@Apache::inputtags::status       - List of problem  statuses. First 
+                                   element is the status of the <problem>
+                                   the remainder are for individual <part>s.
+%Apache::inputtags::params       - Hash of defined parameters for the
+                                   current response.
+@Apache::inputtags::import       - List of all ids for <import> thes get
+                                   join()ed and prepended.
+@Apache::inputtags::importlist   - List of all import ids seen.
+$Apache::inputtags::response_with_no_part
+                                 - Flag set true if we have seen a response
+                                   that is not inside a <part>
+%Apache::inputtags::answertxt    - <*response> tags store correct
+                                   answer strings for display by <textline/>
+                                   in this hash.
+%Apache::inputtags::submission_display
+                                 - <*response> tags store improved display
+                                   of submission strings for display by part
+                                   end.
+
+=cut
 
 sub initialize_inputtags {
     @Apache::inputtags::input=();
@@ -424,14 +454,21 @@
     return "";
 }
 
-# $part -> partid
-# $id -> responseid
-# $uploadefiletypes -> comma seperated list of extensions allowed or * for any
-# $which -> 'uploadedonly'  -> only newly uploaded files
-#           'portfolioonly' -> only allow files from portfolio
-#           'both' -> allow files from either location
-# $extratext -> additional text to go between the link and the input box
-# returns a table row <tr> 
+=pod
+
+=item file_selector()
+
+$part -> partid
+$id -> responseid
+$uploadefiletypes -> comma seperated list of extensions allowed or * for any
+$which -> 'uploadedonly'  -> only newly uploaded files
+          'portfolioonly' -> only allow files from portfolio
+          'both' -> allow files from either location
+$extratext -> additional text to go between the link and the input box
+returns a table row <tr> 
+
+=cut
+
 sub file_selector {
     my ($part,$id,$uploadedfiletypes,$which,$extratext)=@_;
     if (!$uploadedfiletypes) { return ''; }
@@ -1346,4 +1383,10 @@
 
 1;
 __END__
+
+=pod
+
+=back
+
+=cut
  
Index: loncom/homework/randomlabel.pm
diff -u loncom/homework/randomlabel.pm:1.92 loncom/homework/randomlabel.pm:1.93
--- loncom/homework/randomlabel.pm:1.92	Tue Nov 18 19:14:28 2008
+++ loncom/homework/randomlabel.pm	Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # random labelling tool
 #
-# $Id: randomlabel.pm,v 1.92 2008/11/18 19:14:28 jms Exp $
+# $Id: randomlabel.pm,v 1.93 2008/11/25 13:16:17 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -24,35 +24,83 @@
 # /home/httpd/html/adm/gpl.txt
 #
 # http://www.lon-capa.org/
-#
-# SYNTAX:
-# <randomlabel bgimg="URL" width="12" height="45" texwidth="50">
-#    <labelgroup name="GroupOne" type="image">
-#      <location x="123" y="456" />
-#      <location x="321" y="654" />
-#      <location x="213" y="546" />
-#      <label description="TEXT-1">IMG-URL</label>
-#      <label description="TEXT-2">IMG-URL</label>
-#      <label description="TEXT-3">IMG-URL</label>
-#    </labelgroup>
-#    <labelgroup name="GroupTwo" type="text">
-#      <location x="12" y="45" />
-#      <location x="32" y="65" />
-#      <location x="21" y="54" />
-#      <label>TEXT-1</label>
-#      <label>TEXT-2</label>
-#      <label>TEXT-3</label>
-#    </labelgroup>
-#   </randomlabel>
-#  ===========================================
-#  side effect:
-#    location (123,456): $GroupOne[0] = 2  # images give out indexes
-#             (321,654): $GroupOne[1] = 1
-#             (213,546): $GroupOne[2] = 0
-#    location (12,45)  : $GroupTwo[0] = "TEXT-3"
-#             (32,65)  : $GroupTwo[1] = "TEXT-1"
-#             (21,54)  : $GroupTwo[2] = "TEXT-2"
-#  ===========================================
+
+=pod
+
+=head1 NAME
+
+Apache::randomlable.pm
+
+=head1 SYNOPSIS
+
+Interface for producing applet code which
+randomizes the labelling of an image.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 SYNTAX
+
+ <randomlabel bgimg="URL" width="12" height="45" texwidth="50">
+    <labelgroup name="GroupOne" type="image">
+      <location x="123" y="456" />
+      <location x="321" y="654" />
+      <location x="213" y="546" />
+      <label description="TEXT-1">IMG-URL</label>
+      <label description="TEXT-2">IMG-URL</label>
+      <label description="TEXT-3">IMG-URL</label>
+    </labelgroup>
+    <labelgroup name="GroupTwo" type="text">
+      <location x="12" y="45" />
+      <location x="32" y="65" />
+      <location x="21" y="54" />
+      <label>TEXT-1</label>
+      <label>TEXT-2</label>
+      <label>TEXT-3</label>
+    </labelgroup>
+   </randomlabel>
+  ===========================================
+  side effect:
+    location (123,456): $GroupOne[0] = 2   images give out indexes
+             (321,654): $GroupOne[1] = 1
+             (213,546): $GroupOne[2] = 0
+    location (12,45)  : $GroupTwo[0] = "TEXT-3"
+             (32,65)  : $GroupTwo[1] = "TEXT-1"
+             (21,54)  : $GroupTwo[2] = "TEXT-2"
+  ===========================================
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item check_int()
+
+	utility function to do error checking on a integer.
+
+=item extract_tag_sizes()
+
+Parameters:
+      tag         - tag potentially containing height/width attributes.
+      def_width   - Default width.
+      def_height  - Default height.
+  Returns:
+      list containing width/height.
+
+=item get_label_width()
+
+	 Utility sub to compute the width of a label.
+	 
+=item end_labelgroup()
+
+begin to assign labels to locations
+
+=back
+
+=cut
+
+
 
 package Apache::randomlabel;
 use Apache::lonnet;
@@ -90,15 +138,8 @@
     return $num;
 }
 
-#  Get width/height from an image tag...
-#
-#  Parameters:
-#      tag         - tag potentially containing height/width attributes.
-#      def_width   - Default width.
-#      def_height  - Default height.
-#  Returns:
-#      list containing width/height.
-#
+
+
 sub extract_tag_sizes {
     my ($tag, $dw, $dh) = @_;
     $tag =~ s/\s+/ /g;         # Collapse whitespace.
@@ -359,9 +400,8 @@
     return $result;
 }
 
-#
-#   Utility sub to compute the width of a label.
-#
+
+
 sub get_label_width {
     my $label         = shift;
     &Apache::lonxml::debug("image label = $label");
@@ -411,7 +451,8 @@
     $out=Apache::run::run($code,$safeeval);
 }
 
-# begin to assign labels to locations
+
+
 sub end_labelgroup {
     my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
     my $gname = $Apache::randomlabel::groupname;
Index: loncom/homework/response.pm
diff -u loncom/homework/response.pm:1.207 loncom/homework/response.pm:1.208
--- loncom/homework/response.pm:1.207	Mon Nov 24 16:53:26 2008
+++ loncom/homework/response.pm	Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # various response type definitons response definition
 #
-# $Id: response.pm,v 1.207 2008/11/24 16:53:26 jms Exp $
+# $Id: response.pm,v 1.208 2008/11/25 13:16:17 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -26,6 +26,29 @@
 # http://www.lon-capa.org/
 #
 
+=pod
+
+=head1 NAME
+
+Apache::resonse.pm
+
+=head1 SYNOPSIS
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item 
+
+=back
+
+=cut
+
+
 package Apache::response;
 use strict;
 use Apache::lonlocal;
@@ -1153,17 +1176,20 @@
 	$Apache::response::conceptgroup{'names'};
 
 }
-#------------------------------------------------------------
-#
-#  Get a parameter associated with a problem.
-# Parameters:
-#  $id        - the id of the paramater, either a part id, 
-#               or a partid and responspe id joined by _
-#  $name      - Name of the parameter to fetch
-#  $default   - Default value for the paramter.
-#
-#  
-#
+
+=pod
+
+=item get_response_param()
+
+Get a parameter associated with a problem.
+Parameters:
+	$id        - the id of the paramater, either a part id, 
+              or a partid and responspe id joined by _
+	$name      - Name of the parameter to fetch
+	$default   - Default value for the paramter.
+
+=cut
+
 sub get_response_param {
     my ($id,$name,$default)=@_;
     my $parameter;
@@ -1224,14 +1250,21 @@
     }
 }
 
-# basically undef and 0 (both false) mean that they still have work to do
-# and all true values mean that they can't do any more work
-#
-# a return of undef means it is unattempted
-# a return of 0 means it is attmpted and wrong but still has tries
-# a return of 1 means it is marked correct
-# a return of 2 means they have exceed maximum number of tries
-# a return of 3 means it after the answer date
+=pod 
+
+=item check_status()
+
+basically undef and 0 (both false) mean that they still have work to do
+and all true values mean that they can't do any more work
+
+	a return of undef means it is unattempted
+	a return of 0 means it is attmpted and wrong but still has tries
+	a return of 1 means it is marked correct
+	a return of 2 means they have exceed maximum number of tries
+	a return of 3 means it after the answer date
+
+=cut
+
 sub check_status {
     my ($id)=@_;
     if (!defined($id)) { $id=$Apache::inputtags::part; }
@@ -1299,3 +1332,8 @@
 1;
 __END__
  
+=pod
+
+=back
+
+=cut
\ No newline at end of file
Index: loncom/homework/lonhomework.pm
diff -u loncom/homework/lonhomework.pm:1.299 loncom/homework/lonhomework.pm:1.300
--- loncom/homework/lonhomework.pm:1.299	Wed Nov 19 18:34:56 2008
+++ loncom/homework/lonhomework.pm	Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # The LON-CAPA Homework handler
 #
-# $Id: lonhomework.pm,v 1.299 2008/11/19 18:34:56 jms Exp $
+# $Id: lonhomework.pm,v 1.300 2008/11/25 13:16:17 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -25,6 +25,25 @@
 #
 # http://www.lon-capa.org/
 
+=pod
+
+=head1 NAME
+
+Apache::lonhomework.pm
+
+=head1 SYNOPSIS
+
+handles requests for output, evaluation, and
+alteration of a homework resource
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=cut
+
 
 package Apache::lonhomework;
 use strict;
Index: loncom/homework/structuretags.pm
diff -u loncom/homework/structuretags.pm:1.434 loncom/homework/structuretags.pm:1.435
--- loncom/homework/structuretags.pm:1.434	Mon Nov 10 11:44:54 2008
+++ loncom/homework/structuretags.pm	Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA 
 # definition of tags that give a structure to a document
 #
-# $Id: structuretags.pm,v 1.434 2008/11/10 11:44:54 foxr Exp $
+# $Id: structuretags.pm,v 1.435 2008/11/25 13:16:17 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -27,6 +27,29 @@
 #
 ###
 
+=pod
+
+=head1 NAME
+
+Apache::structuretags
+
+=head1 SYNOPSIS
+
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item 
+
+=back
+
+=cut
+
 
 package Apache::structuretags; 
 
@@ -551,12 +574,19 @@
     if ($temp =~ m/^error:.*/) { %Apache::lonhomework::history=(); }
 }
 
-# -------------------------------------------------------------finalize_storage
-# Stores away the result has to a student's environment
-# checks form.grade_ for specific values, other wises stores
-# to the running users environment
-# Will increment totals for attempts, students, and corrects
-# if running user has student role.  
+=pod
+
+=item finalize_storage()
+
+	Stores away the result has to a student's environment
+	checks form.grade_ for specific values, other wises stores
+	to the running users environment
+	Will increment totals for attempts, students, and corrects
+	if running user has student role.
+	
+=cut
+
+
 sub finalize_storage {
     my ($given_symb) = @_;
     my $result;
@@ -587,10 +617,16 @@
     return $result;
 }
 
-# -------------------------------------------------------------store_aggregates
-# Sends hash of values to be incremented in nohist_resourcetracker.db
-# for the course. Increments total number of attempts, unique students 
-# and corrects for each part for an instance of a problem, as appropriate.
+=pod
+
+item store_aggregates()
+
+	Sends hash of values to be incremented in nohist_resourcetracker.db
+	for the course. Increments total number of attempts, unique students 
+	and corrects for each part for an instance of a problem, as appropriate.
+	
+=cut
+
 sub store_aggregates {
     my ($symb,$courseid) = @_;
     my %aggregate;
@@ -2002,3 +2038,9 @@
 
 1;
 __END__
+
+=pod
+
+=back
+
+=cut
Index: loncom/enrollment/localenroll.pm
diff -u loncom/enrollment/localenroll.pm:1.31 loncom/enrollment/localenroll.pm:1.32
--- loncom/enrollment/localenroll.pm:1.31	Fri Feb 29 21:01:43 2008
+++ loncom/enrollment/localenroll.pm	Tue Nov 25 13:16:26 2008
@@ -1,6 +1,6 @@
 # functions to glue school database system into Lon-CAPA for 
 # automated enrollment
-# $Id: localenroll.pm,v 1.31 2008/02/29 21:01:43 raeburn Exp $
+# $Id: localenroll.pm,v 1.32 2008/11/25 13:16:26 jms Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -24,128 +24,154 @@
 #
 # http://www.lon-capa.org/
 #
+
+=pod
+
+=head1 NAME
+
+localenroll
+
+=head1 SYNOPSIS
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=back
+
+=cut
+
 package localenroll;
 
 use strict;
 
-################################
-# sub run
-# set this to return 1 if you want the auto enrollment to run
-#
-# Beginning with LON-CAPA version 2.4, use of this routine is
-# deprecated.  Whether or not Autoenroll.pl should run is set
-# by the Domain Coordinator via "Set domain configuration",
-# provided in the Domain Management section of the Main menu. 
-################################
+=pod
+ 
+=item run()
+ set this to return 1 if you want the auto enrollment to run
+
+ Beginning with LON-CAPA version 2.4, use of this routine is
+ deprecated.  Whether or not Autoenroll.pl should run is set
+ by the Domain Coordinator via "Set domain configuration",
+ provided in the Domain Management section of the Main menu. 
+
+=cut
 
 sub run() {
     my $dom = shift;
     return 0;
 }
 
-################################
-# sub fetch_enrollment
-#
-# connects to the institutional classlist data source,
-# reads classlist data and stores in an XML file
-# in /home/httpd/perl/tmp/
-#
-# classlist files are named as follows:
-#
-# DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
-#
-# e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
-# where DOMAIN = msu  COURSE = 43551dedcd43febmsul1 
-# INSTITUTIONALCODE = fs03nop590001 
-# (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
-# department name, 590 = course number, 001 = section number.)
-#
-# fetch_enrollment requires three arguments -
-# $dom - DOMAIN e.g., msu
-# $affiliatesref - a reference to a hash of arrays that contains LON-CAPA 
-# courses that are to be updated as keys, and institutional coursecodes 
-# contributing enrollment to that LON-CAPA course as elements in each array.
-# $replyref - a reference to a hash that contains LON-CAPA courses
-# that are to be updated as keys, and the total enrollment count in all 
-# affiliated sections, as determined from institutional data as hash elements. 
-#
-# As an example, if fetch_enrollment is called to retrieve institutional
-# classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which 
-# corresponds to fs03nop590, sections 001, 601 and 602 , and the course
-# also accommodates enrollment from a crosslisted course in the ost
-# department - fs03ost580002:
-#
-# the affiliatesref would be a reference to %affiliates which would be:
-#
-# @{$affiliates{'43551dedcd43febmsul1'}} =
-#   ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
-#
-# fetch_enrollment would create four files in /home/httpd/perl/tmp/.
-# msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
-# msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
-# msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
-# msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
-#
-# In each file, student data would be stored in the following format
-# 
-# <student username="smith">
-#  <autharg>MSU.EDU</autharg>
-#  <authtype>krb4</authtype>
-#  <email>smith@msu.edu</email>
-#  <enddate></enddate>
-#  <firstname>John</firstname>
-#  <generation>II</generation>
-#  <groupID>fs03nop590001</groupID>
-#  <lastname>Smith</lastname>
-#  <middlename>D</middlename>
-#  <startdate></startdate>
-#  <studentID>A12345678</studentID>
-# </student>
-# 
-# with the following at the top of the file
-#<?xml version="1.0" encoding="UTF-8"?>
-#<!DOCTYPE text>
-#<students>
-#
-# (all comment - #s removed)
-#
-# and a closing:
-#</students>
-#
-# The <startdate> and the <enddate> are the activation date and expiration date
-# for this student's role. If they are absent, then the default access start and
-# default access end dates are used. The default access dates can be set when 
-# the course is created, and can be modified using the Automated Enrollment
-# Manager, or via the 'Upload a class list','Enroll a single student' or 
-# 'Modify student data' utilities in the Enrollment Manager, by checking the 
-# 'make these dates the default for future enrollment' checkbox. If no default 
-# dates have been set, then the tudent role will be active immediately, and will 
-# remain active until the role is explicitly expired using ENRL -> Drop students. 
-# If dates are to included in the XML file, they should be in the format
-# YYYY:MM:DD:HH:MM:SS (: separators required).
-#
-# If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 
-# 8 students in fs03nop590602, and 2 students in fs03ost580002,
-# then $$reply{'43551dedcd43febmsul1'} = 25
-#
-# The purpose of the %reply hash is to detect cases where the institutional 
-# enrollment is 0 (most likely due to a problem with the data source).
-# In such a case, the LON-CAPA course roster is left unchanged (i.e., no
-# students are expired, even if automated drops is enabled.
-# 
-# fetch_enrollment should return a 0 or 1, depending on whether a connection
-# could be established to the institutional data source.
-# 0 is returned if no connection could be made.
-# 1 is returned if connection was successful
-#
-# A return of 1 is required for the calling modules to perform LON-CAPA
-# roster changes based on the contents of the XML classlist file(s), e,g,,
-# msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
-#
-# XML classlist files are temporary. They are deleted after the enrollment 
-# update process in the calling module is complete.
-#
-################################
+
+=pod
+
+=item fetch_enrollment()
+
+ connects to the institutional classlist data source,
+ reads classlist data and stores in an XML file
+ in /home/httpd/perl/tmp/
+
+ classlist files are named as follows:
+
+ DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
+
+ e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
+ where DOMAIN = msu  COURSE = 43551dedcd43febmsul1 
+ INSTITUTIONALCODE = fs03nop590001 
+ (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
+ department name, 590 = course number, 001 = section number.)
+
+ fetch_enrollment requires three arguments -
+ $dom - DOMAIN e.g., msu
+ $affiliatesref - a reference to a hash of arrays that contains LON-CAPA 
+ courses that are to be updated as keys, and institutional coursecodes 
+ contributing enrollment to that LON-CAPA course as elements in each array.
+ $replyref - a reference to a hash that contains LON-CAPA courses
+ that are to be updated as keys, and the total enrollment count in all 
+ affiliated sections, as determined from institutional data as hash elements. 
+
+ As an example, if fetch_enrollment is called to retrieve institutional
+ classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which 
+ corresponds to fs03nop590, sections 001, 601 and 602 , and the course
+ also accommodates enrollment from a crosslisted course in the ost
+ department - fs03ost580002:
+
+ the affiliatesref would be a reference to %affiliates which would be:
+
+ @{$affiliates{'43551dedcd43febmsul1'}} =
+   ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
+
+ fetch_enrollment would create four files in /home/httpd/perl/tmp/.
+ msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
+ msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
+ msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
+ msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
+
+ In each file, student data would be stored in the following format
+ 
+ <student username="smith">
+  <autharg>MSU.EDU</autharg>
+  <authtype>krb4</authtype>
+  <email>smith@msu.edu</email>
+  <enddate></enddate>
+  <firstname>John</firstname>
+  <generation>II</generation>
+  <groupID>fs03nop590001</groupID>
+  <lastname>Smith</lastname>
+  <middlename>D</middlename>
+  <startdate></startdate>
+  <studentID>A12345678</studentID>
+ </student>
+ 
+ with the following at the top of the file
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE text>
+<students>
+
+ (all comment - s removed)
+
+ and a closing:
+</students>
+
+ The <startdate> and the <enddate> are the activation date and expiration date
+ for this student's role. If they are absent, then the default access start and
+ default access end dates are used. The default access dates can be set when 
+ the course is created, and can be modified using the Automated Enrollment
+ Manager, or via the 'Upload a class list','Enroll a single student' or 
+ 'Modify student data' utilities in the Enrollment Manager, by checking the 
+ 'make these dates the default for future enrollment' checkbox. If no default 
+ dates have been set, then the tudent role will be active immediately, and will 
+ remain active until the role is explicitly expired using ENRL -> Drop students. 
+ If dates are to included in the XML file, they should be in the format
+ YYYY:MM:DD:HH:MM:SS (: separators required).
+
+ If there were 10 students in fs03nop590001, 5 students in fs03nop59o601, 
+ 8 students in fs03nop590602, and 2 students in fs03ost580002,
+ then $$reply{'43551dedcd43febmsul1'} = 25
+
+ The purpose of the %reply hash is to detect cases where the institutional 
+ enrollment is 0 (most likely due to a problem with the data source).
+ In such a case, the LON-CAPA course roster is left unchanged (i.e., no
+ students are expired, even if automated drops is enabled.
+ 
+ fetch_enrollment should return a 0 or 1, depending on whether a connection
+ could be established to the institutional data source.
+ 0 is returned if no connection could be made.
+ 1 is returned if connection was successful
+
+ A return of 1 is required for the calling modules to perform LON-CAPA
+ roster changes based on the contents of the XML classlist file(s), e,g,,
+ msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
+
+ XML classlist files are temporary. They are deleted after the enrollment 
+ update process in the calling module is complete.
+
+
+=cut
 
 sub fetch_enrollment {
     my ($dom,$affiliatesref,$replyref) = @_;
@@ -156,30 +182,33 @@
     return $okflag;
 }
 
-###############################
-# sub get_sections
-#
-# This is called by the Automated Enrollment Manager interface
-# (lonpopulate.pm) to create an array of valid sections for 
-# a specific institutional coursecode.
-# e.g., for MSU coursecode: fs03nop590
-# ("001","601","602") would be returned
-#
-# If the array returned contains at least one element, then 
-# the interface offerred to the course coordinator, lists
-# official sections and provides a checkbox to use to
-# select enrollment in the LON-CAPA course from each official section.  
-#
-# get_sections takes two arguments - (a) the institutional coursecode
-# (in the MSU case this is a concatenation of semester code, department
-# and course number), and (b) the LON-CAPA domain that contains the course. 
-# 
-# If there is no access to official course sections at your institution,
-# then an empty array is returned, and the Automated Enrollment Manager
-# interface will allow the course coordinator to enter section numbers
-# in text boxes.
-# 
-###############################
+=pod
+
+=item get_sections()
+
+ This is called by the Automated Enrollment Manager interface
+ (lonpopulate.pm) to create an array of valid sections for 
+ a specific institutional coursecode.
+ e.g., for MSU coursecode: fs03nop590
+ ("001","601","602") would be returned
+
+ If the array returned contains at least one element, then 
+ the interface offerred to the course coordinator, lists
+ official sections and provides a checkbox to use to
+ select enrollment in the LON-CAPA course from each official section.  
+
+ get_sections takes two arguments - (a) the institutional coursecode
+ (in the MSU case this is a concatenation of semester code, department
+ and course number), and (b) the LON-CAPA domain that contains the course. 
+ 
+ If there is no access to official course sections at your institution,
+ then an empty array is returned, and the Automated Enrollment Manager
+ interface will allow the course coordinator to enter section numbers
+ in text boxes.
+ 
+
+
+=cut
 
 sub get_sections {
     my ($coursecode,$dom) = @_;
@@ -187,34 +216,35 @@
     return @secs;
 }
 
-###############################
-# sub new_course
-#
-# This is called by loncreatecourse.pm and 
-# lonpopulate.pm to record that fact that a new course section
-# has been added to LON-CAPA that requires access to institutional data
-# At MSU, this is required, as institutional classlists can only made
-# available to faculty who are officially assigned to a course.
-# 
-# The new_course subroutine is used to check that the course owner
-# of the LON-CAPA course is permitted to access the institutional
-# classlist for any course sections and crosslisted classes that
-# the course coordinator wishes to have affiliated with the course.
-# 
-# If access is permitted, then 'ok' is returned.
-# The course section or crosslisted course will only be added to the list of
-# affiliates if 'ok' is returned.
-#
-# new_course takes three arguments -
-# (a) the institutional courseID (in the MSU case this is a concatenation of 
-# semester code, department code, course number, and section number
-# e.g., fs03nop590001).
-# (b) the course owner. This is the LON-CAPA username and domain of the course 
-# coordinator assigned to the course when it is first created, in the form
-# username:domain
-# (c) the LON-CAPA domain that contains the course
-#
-#################################
+=pod
+
+=item new_course()
+
+ This is called by loncreatecourse.pm and 
+ lonpopulate.pm to record that fact that a new course section
+ has been added to LON-CAPA that requires access to institutional data
+ At MSU, this is required, as institutional classlists can only made
+ available to faculty who are officially assigned to a course.
+ 
+ The new_course subroutine is used to check that the course owner
+ of the LON-CAPA course is permitted to access the institutional
+ classlist for any course sections and crosslisted classes that
+ the course coordinator wishes to have affiliated with the course.
+ 
+ If access is permitted, then 'ok' is returned.
+ The course section or crosslisted course will only be added to the list of
+ affiliates if 'ok' is returned.
+
+ new_course takes three arguments -
+ (a) the institutional courseID (in the MSU case this is a concatenation of 
+ semester code, department code, course number, and section number
+ e.g., fs03nop590001).
+ (b) the course owner. This is the LON-CAPA username and domain of the course 
+ coordinator assigned to the course when it is first created, in the form
+ username:domain
+ (c) the LON-CAPA domain that contains the course
+
+=cut
 
 sub new_course  {
     my ($course_id,$owner,$dom) = @_;
@@ -222,25 +252,26 @@
     return $outcome;
 }
 
-###############################
-# sub validate_courseID
-#
-# This is called whenever a new course section or crosslisted course
-# is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
-# and the Automated Enrollment Manager in lonpopulate.pm).
-# A check is made that the courseID that the course coordinator wishes
-# to affiliate with the course is valid according to the institutional
-# schedule of official classes 
-#
-# A valid courseID is confirmed by returning 'ok'
-#
-# validate_courseID takes two arguments -
-# (a) the institutional courseID (in the MSU case this is a concatenation of
-# semester code, department code, course number, and section number
-# e.g., fs03nop590001).
-# (b) the LON-CAPA domain that contains the course
-#
-###############################  
+=pod
+
+=item validate_courseID()
+
+ This is called whenever a new course section or crosslisted course
+ is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
+ and the Automated Enrollment Manager in lonpopulate.pm).
+ A check is made that the courseID that the course coordinator wishes
+ to affiliate with the course is valid according to the institutional
+ schedule of official classes 
+
+ A valid courseID is confirmed by returning 'ok'
+
+ validate_courseID takes two arguments -
+ (a) the institutional courseID (in the MSU case this is a concatenation of
+ semester code, department code, course number, and section number
+ e.g., fs03nop590001).
+ (b) the LON-CAPA domain that contains the course
+
+=cut  
 
 sub validate_courseID {
     my ($course_id,$dom) = @_;
@@ -248,48 +279,51 @@
     return $outcome;   
 }
 
-###############################
-# sub create_password 
-#
-# This is called when the authentication method set for the automated 
-# enrollment process when enrolling new users in the domain is "localauth".
-# This could be signalled for the specific user by the value of localauth
-# for the <authtype> tag from the classlist.xml files, or if this is blank,
-# the default authtype, set by the domain coordinator when creating the course
-# with loncreatecourse.pm.
-#  
-# create_password takes three arguments -
-# (a) $authparam - the value of <autharg> from the classlist.xml files,
-# or if this blank, the default autharg, set by the domain coordinator when 
-# creating the course with loncreatecourse.pm
-# (b) $dom - the domain of the new user.
-# (c) $username - the username of the new user (currently not actually used)
-#
-# Four values are returned:
-# (a) the value of $authparam - which might have been changed
-# (b) a flag to indicate whether a password had been created
-# 0 means no password created
-# 1 means password created.  In this case the calling module - Enrollment.pm
-# will send the LON-CAPA username and password to the new user's e-mail
-# (if one was provided), or to the course owner (if one was not provided and
-# the new user was created by the automated process), or to the active
-# course coordinator (if the new user was created using the 'update roster
-# now' interface included in the Automated Enrollment Manager).  
-# (c) a flag to indicate that the authentication method is correct - 'ok'.
-# If $authchk is not set to 'ok' then account creation and enrollment of the 
-# new user will not occur.
-# (d) if a password was created it can be sent along.  This is the password 
-# which will be included in the e-mail sent to the new user, or made available    
-# to the course owner/course coordinator if no e-mail address is provided. If
-# you do not wish to send a password, but want to give instructions on obtaining
-# one, you could set $newpasswd as those instructions. (e.g.,
-# $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';
-# The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in
-# /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user
-# employing localauth will contain 'localauth:$authparam'.  If you need to include
-# a parameter in the user's passwd file, you should return it as $authparam,
-# i.e., the first of the variables returned by create_password().             
-###############################
+=pod
+
+=item create_password()
+
+ This is called when the authentication method set for the automated 
+ enrollment process when enrolling new users in the domain is "localauth".
+ This could be signalled for the specific user by the value of localauth
+ for the <authtype> tag from the classlist.xml files, or if this is blank,
+ the default authtype, set by the domain coordinator when creating the course
+ with loncreatecourse.pm.
+  
+ create_password takes three arguments -
+ (a) $authparam - the value of <autharg> from the classlist.xml files,
+ or if this blank, the default autharg, set by the domain coordinator when 
+ creating the course with loncreatecourse.pm
+ (b) $dom - the domain of the new user.
+ (c) $username - the username of the new user (currently not actually used)
+
+ Four values are returned:
+ (a) the value of $authparam - which might have been changed
+ (b) a flag to indicate whether a password had been created
+ 0 means no password created
+ 1 means password created.  In this case the calling module - Enrollment.pm
+ will send the LON-CAPA username and password to the new user's e-mail
+ (if one was provided), or to the course owner (if one was not provided and
+ the new user was created by the automated process), or to the active
+ course coordinator (if the new user was created using the 'update roster
+ now' interface included in the Automated Enrollment Manager).  
+ (c) a flag to indicate that the authentication method is correct - 'ok'.
+ If $authchk is not set to 'ok' then account creation and enrollment of the 
+ new user will not occur.
+ (d) if a password was created it can be sent along.  This is the password 
+ which will be included in the e-mail sent to the new user, or made available    
+ to the course owner/course coordinator if no e-mail address is provided. If
+ you do not wish to send a password, but want to give instructions on obtaining
+ one, you could set $newpasswd as those instructions. (e.g.,
+ $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';
+ The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in
+ /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user
+ employing localauth will contain 'localauth:$authparam'.  If you need to include
+ a parameter in the user's passwd file, you should return it as $authparam,
+ i.e., the first of the variables returned by create_password().             
+
+
+=cut 
 
 sub create_password {
     my ($authparam,$dom,$username) = @_;
@@ -299,41 +333,44 @@
     return ($authparam,$create_passwd,$authchk,$newpasswd);
 }
 
-###############################
-# sub instcode_format 
-#
-# Split coursecodes into constituent parts.   
-# e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1
-# (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
-# department name, 590 = course number)
-#
-# Incoming data:
-# $dom (domain)
-# $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs)
-# 
-# fs03nop590 would be split as follows
-# @{$codetitles} = ("year","semester","department","number")
-# $$codes{{'year'} = '2003'
-# $$codes{'semester'} = 'Fall'
-# $$codes{'department'} = 'nop'
-# $$codes{'number'} = '590'
-#
-# requires six arguments:
-# domain ($dom)
-# reference to hash of institutional course IDs ($instcodes)  
-# reference to hash of codes ($codes)
-# reference to array of titles ($codetitles)
-# reference to hash of abbreviations used in categories
-# reference to hash of arrays specifying sort order used in category titles   
-#
-# e.g.,     %{$$cat_titles{'Semester'}} = (
-#                   fs => 'Fall',
-#                   ss => 'Spring',
-#                   us => 'Summer');
-#
-# e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 
-# returns 1 parameter: 'ok' if no processing errors.  
-###############################
+=pod
+
+=item instcode_format()
+
+ Split coursecodes into constituent parts.   
+ e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1
+ (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
+ department name, 590 = course number)
+
+ Incoming data:
+ $dom (domain)
+ $$instcodes{'43551dedcd43febmsul1'} = 'fs03nop590' (hash of courseIDs)
+ 
+ fs03nop590 would be split as follows
+ @{$codetitles} = ("year","semester","department","number")
+ $$codes{{'year'} = '2003'
+ $$codes{'semester'} = 'Fall'
+ $$codes{'department'} = 'nop'
+ $$codes{'number'} = '590'
+
+ requires six arguments:
+ domain ($dom)
+ reference to hash of institutional course IDs ($instcodes)  
+ reference to hash of codes ($codes)
+ reference to array of titles ($codetitles)
+ reference to hash of abbreviations used in categories
+ reference to hash of arrays specifying sort order used in category titles   
+
+ e.g.,     %{$$cat_titles{'Semester'}} = (
+                   fs => 'Fall',
+                   ss => 'Spring',
+                   us => 'Summer');
+
+ e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 
+ returns 1 parameter: 'ok' if no processing errors. 
+ 
+=cut
+
 
 sub instcode_format () {
     my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;
@@ -341,35 +378,38 @@
     return $outcome;
 }
 
-###############################
-# sub institutional_photos
-#
-# Called when automated enrollment manager is used to update student photos.
-#
-# Incoming data: six arguments
-# (a) $dom (domain)
-# (b) $crs (LONCAPA course number)
-# (c) $affiliates: a reference to a hash with the keys set to the 
-# institutional course IDs for the course.
-# (d) $result: a reference to a hash which will return usernames  
-#     of students (& separated) in following categories (the keys):
-#     new, update, missing, same, deleted, noid, nouser. The list 
-#     includes those students for whom the result of the modification 
-#     process was either addition of a new photo. update of an
-#     existing photo, photo was found to be missing from institution's
-#     data store, photo used is same as before, or photo was 
-#     deleted from storage on LON-CAPA server housing student's
-#     information, no student ID was available. 
+
+=pod
+
+=item institutional_photos()
+
+ Called when automated enrollment manager is used to update student photos.
+
+ Incoming data: six arguments
+ (a) $dom (domain)
+ (b) $crs (LONCAPA course number)
+ (c) $affiliates: a reference to a hash with the keys set to the 
+ institutional course IDs for the course.
+ (d) $result: a reference to a hash which will return usernames  
+     of students (& separated) in following categories (the keys):
+     new, update, missing, same, deleted, noid, nouser. The list 
+     includes those students for whom the result of the modification 
+     process was either addition of a new photo. update of an
+     existing photo, photo was found to be missing from institution's
+     data store, photo used is same as before, or photo was 
+     deleted from storage on LON-CAPA server housing student's
+     information, no student ID was available. 
                
-# (e) $action: the type of action needed. (e.g., update, delete);
-# (f) $students: a reference to a hash with the keys set to student 
-# usernames and domains in the form username:domain, and values set
-# to the studentID, if action is required for specific students.  
-#
-# returns 1 parameter: 'ok' if no processing errors.
-# other course or student specific values can be stored as values
-# in the appropriate referenced hashes. 
-###############################
+ (e) $action: the type of action needed. (e.g., update, delete);
+ (f) $students: a reference to a hash with the keys set to student 
+ usernames and domains in the form username:domain, and values set
+ to the studentID, if action is required for specific students.  
+
+ returns 1 parameter: 'ok' if no processing errors.
+ other course or student specific values can be stored as values
+ in the appropriate referenced hashes. 
+
+=cut
 
 sub institutional_photos {
     my ($dom,$crs,$affiliates,$result,$action,$students) = @_;
@@ -377,22 +417,25 @@
     return $outcome;
 }
 
-###############################
-# sub photo_permission
-#
-# Incoming data: three arguments
-# (a) $dom (domain)
-# (b) $perm_reqd: a reference to a a scalar that is either 'yes'
-# if a course owner must indicate acceptance of conditions of use,
-# 'no' otherwise.
-# (c) $conditions: the text of the conditions of use.
-#    
-# returns 1 parameter: 'ok' if no processing errors.
-# $$perm_reqd is set to 'yes' or 'no'
-# $$agreement is set to conditions of use - plain text string
-#             which will be displayed in a textarea in a web form.
-###############################
- 
+=pod
+
+=item photo_permission()
+
+ Incoming data: three arguments
+ (a) $dom (domain)
+ (b) $perm_reqd: a reference to a a scalar that is either 'yes'
+ if a course owner must indicate acceptance of conditions of use,
+ 'no' otherwise.
+ (c) $conditions: the text of the conditions of use.
+    
+ returns 1 parameter: 'ok' if no processing errors.
+ $$perm_reqd is set to 'yes' or 'no'
+ $$agreement is set to conditions of use - plain text string
+             which will be displayed in a textarea in a web form.
+
+
+=cut
+
 sub photo_permission {
    my ($dom,$perm_reqd,$conditions) = @_;
    $$perm_reqd = 'no';
@@ -401,19 +444,21 @@
    return $outcome;
 }
 
+=pod
 
-###############################
-# sub manager_photo_update
-#
-# Incoming data: one argument
-# (a) $dom (domain)
-#
-# returns 2 parameters: update (0 or 1), and comment.
-# Called by automated enrollment manager, to determine 
-# whether "Update Student photos" button will be available,
-# and if so, the message (plain text string) that will be displayed
-# with the button. 
-###############################
+=item manager_photo_update()
+
+ Incoming data: one argument
+ (a) $dom (domain)
+
+ returns 2 parameters: update (0 or 1), and comment.
+ Called by automated enrollment manager, to determine 
+ whether "Update Student photos" button will be available,
+ and if so, the message (plain text string) that will be displayed
+ with the button. 
+
+
+=cut
                                                                                         
 sub manager_photo_update {
     my ($dom) = @_;
@@ -422,22 +467,26 @@
     return ($update,$comment);
 }
 
-###############################
-# sub check_section
-#
-# Incoming data: three arguments (+ fourth optional argument)
-# (a) $class - institutional class id (coursecode concatanated with section) 
-# (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
-#                            2.6 and later - comma-separated list of 
-#                            username:domain for course owner and co-owners.)
-# (c) $dom - domain of course
-# (d) $dbh - optional database handle
-#
-# returns 1 parameter - $sectioncheck ('ok' or other value). 
-# Verifies that at least one of the course owner (or co-owners) have access 
-# to classlist for specific class according to institution's SIS
-# 'ok' if access available  
-###############################
+=pod
+
+
+=item check_section()
+
+ Incoming data: three arguments (+ fourth optional argument)
+ (a) $class - institutional class id (coursecode concatanated with section) 
+ (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
+                            2.6 and later - comma-separated list of 
+                            username:domain for course owner and co-owners.)
+ (c) $dom - domain of course
+ (d) $dbh - optional database handle
+
+ returns 1 parameter - $sectioncheck ('ok' or other value). 
+ Verifies that at least one of the course owner (or co-owners) have access 
+ to classlist for specific class according to institution's SIS
+ 'ok' if access available  
+
+
+=cut
 
 sub check_section {
     my ($class,$owner,$dom,$dbh) = @_;
@@ -445,67 +494,71 @@
     return $sectioncheck;
 }
 
-###############################
-# sub instcode_defaults
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $defaults - reference to hash which will contain default regular
-#                 expression matches for different components of an 
-#                 institutional course code 
-# (c) $code_order - reference to array which will contain order of 
-#                   component parts used in institutional code.  
-#
-# returns 1 parameter - ('ok' or other value).
-# Used to construct a regular expression to be used when searching for
-# courses based on fragments of an institutional code.
-# $defaults contains defaults to use for each component, and code_order
-# contains keys of hash in order in which they are to be concatenated.
-#
-# e.g., INSTITUTIONALCODE = fs03nop590
-# (MSU's course naming scheme - fs  = semester, 03 = year, nop =
-# department name, 590 = course number)
-#
-#     %{$defaults} = (
-#        'Year' => '\d{2}',
-#        'Semester' => '^[sfu]s', 
-#        'Department' => '\w{2,3}',
-#        'Number' => '\d{3,4}\w?',
-#     );
-#
-#     @{$code_order} = ('Semester','Year','Department','Number');
-#
-###############################
+=pod
+
+=item instcode_defaults()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $defaults - reference to hash which will contain default regular
+                 expression matches for different components of an 
+                 institutional course code 
+ (c) $code_order - reference to array which will contain order of 
+                   component parts used in institutional code.  
+
+ returns 1 parameter - ('ok' or other value).
+ Used to construct a regular expression to be used when searching for
+ courses based on fragments of an institutional code.
+ $defaults contains defaults to use for each component, and code_order
+ contains keys of hash in order in which they are to be concatenated.
+
+ e.g., INSTITUTIONALCODE = fs03nop590
+ (MSU's course naming scheme - fs  = semester, 03 = year, nop =
+ department name, 590 = course number)
+
+     %{$defaults} = (
+        'Year' => '\d{2}',
+        'Semester' => '^[sfu]s', 
+        'Department' => '\w{2,3}',
+        'Number' => '\d{3,4}\w?',
+     );
+
+     @{$code_order} = ('Semester','Year','Department','Number');
+
+=cut
 
 sub instcode_defaults {
     my ($dom,$defaults,$code_order) = @_;
     return 'ok';
 }
 
-###############################
-# sub allusers_info
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $instusers - reference to hash which will contain hashes, 
-#                 where keys will be usernames and value will be a 
-#                 hash of user information. Keys in the inner hash 
-#                 will be some or all of: lastname,firstname,
-#                 middlename, generation, id, inststatus - 
-#                 institutional status (e.g., faculty,staff,student)
-#                 Values are all scalars except inststatus,
-#                 which is an array.
-# (c) $instids - reference to hash which will contain ID numbers. 
-#                keys will be unique IDs (student or faculty/staff ID)
-#                values will be either: scalar (username) or an array 
-#                if a single ID matches multiple usernames.
-# returns 1 parameter - 'ok' if no processing error, or other value 
-#                       if an error occurred.
-# side effects - populates the $instusers and $instids refs to hashes.
-#                with information for all users from all available 
-#                institutional datafeeds.
-#
-###############################
+
+=pod
+
+=item allusers_info()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $instusers - reference to hash which will contain hashes, 
+                 where keys will be usernames and value will be a 
+                 hash of user information. Keys in the inner hash 
+                 will be some or all of: lastname,firstname,
+                 middlename, generation, id, inststatus - 
+                 institutional status (e.g., faculty,staff,student)
+                 Values are all scalars except inststatus,
+                 which is an array.
+ (c) $instids - reference to hash which will contain ID numbers. 
+                keys will be unique IDs (student or faculty/staff ID)
+                values will be either: scalar (username) or an array 
+                if a single ID matches multiple usernames.
+ returns 1 parameter - 'ok' if no processing error, or other value 
+                       if an error occurred.
+ side effects - populates the $instusers and $instids refs to hashes.
+                with information for all users from all available 
+                institutional datafeeds.
+
+
+=cut
 
 sub allusers_info {
     my ($dom,$instusers,$instids) = @_;
@@ -513,58 +566,59 @@
     return $outcome; 
 }
 
-###############################
-# sub get_userinfo
-#
-# Incoming data: four required arguments and additional optional arguments
-# Two modes of operation:
-# (1) Retrieves institutional data for a single user either by username
-#     if $uname is included as second argument, or by ID if $id is 
-#     included as a third argument.  Either (b) or (c) must be provided.
-#     (g), (h) and (i) will be undefined.
-# (2) Retrieves institutional user data from search of an institutional
-#     directory based on a search. (g) and (h) are required.
-#     (i) is optional. (b) and (c) will be undefined. 
-#
-# (a) $dom - domain
-# (b) $uname - username of user
-# (c) $id - student/faculty ID of user
-# (d) $instusers - reference to hash which will contain info for user
-#                 as key = value; keys will be one or all of:
-#                 lastname,firstname,middlename,generation,id,inststatus -
-#                 institutional status (e.g., faculty,staff,student)
-#                 Values are all scalars except inststatus,
-#                 which is an array.
-# (e) $instids - reference to hash which will contain ID numbers - 
-#                 keys will be unique IDs (student or faculty/staff ID)  
-#                 values will be either: scalar (username) or an array
-#                 if a single ID matches multiple usernames.
-# (f) $types - optional reference to array which contains 
-#              institutional types to check.
-# (g) $srchby - optional if $uname or $id defined, otherwise required.
-#               Allowed values include: 1. lastfirst, 2. last, 3. uname
-#               corresponding to searches by 1. lastname,firstname;
-#               2. lastname; 3. username
-# (h) $srchterm - optional if $uname or $id defined, otherwise required
-#                String to search for.
-# (i) $srchtype - optional. Allowed values: contains, begins (defaults
-#                to exact match otherwise).
-#
-# returns 1 parameter - 'ok' if no processing error, or other value 
-#                       if an error occurred.
-# side effects - populates the $instusers and $instids refs to hashes.
-#                with information for specified username, or specified
-#                id, if fifth argument provided, from all available, or 
-#                specified (e.g., faculty only) institutional datafeeds,
-#                if sixth argument provided.
-#
-# WARNING: You need to set $outcome to 'ok' once you have customized
-#          this routine to communicate with an instititional 
-#          directory data source, otherwise institutional directory 
-#          searches will always be reported as being unavailable
-#          in domain $dom.
-#
-###############################
+=pod
+
+=item get_userinfo()
+
+ Incoming data: four required arguments and additional optional arguments
+ Two modes of operation:
+ (1) Retrieves institutional data for a single user either by username
+     if $uname is included as second argument, or by ID if $id is 
+     included as a third argument.  Either (b) or (c) must be provided.
+     (g), (h) and (i) will be undefined.
+ (2) Retrieves institutional user data from search of an institutional
+     directory based on a search. (g) and (h) are required.
+     (i) is optional. (b) and (c) will be undefined. 
+
+ (a) $dom - domain
+ (b) $uname - username of user
+ (c) $id - student/faculty ID of user
+ (d) $instusers - reference to hash which will contain info for user
+                 as key = value; keys will be one or all of:
+                 lastname,firstname,middlename,generation,id,inststatus -
+                 institutional status (e.g., faculty,staff,student)
+                 Values are all scalars except inststatus,
+                 which is an array.
+ (e) $instids - reference to hash which will contain ID numbers - 
+                 keys will be unique IDs (student or faculty/staff ID)  
+                 values will be either: scalar (username) or an array
+                 if a single ID matches multiple usernames.
+ (f) $types - optional reference to array which contains 
+              institutional types to check.
+ (g) $srchby - optional if $uname or $id defined, otherwise required.
+               Allowed values include: 1. lastfirst, 2. last, 3. uname
+               corresponding to searches by 1. lastname,firstname;
+               2. lastname; 3. username
+ (h) $srchterm - optional if $uname or $id defined, otherwise required
+                String to search for.
+ (i) $srchtype - optional. Allowed values: contains, begins (defaults
+                to exact match otherwise).
+
+ returns 1 parameter - 'ok' if no processing error, or other value 
+                       if an error occurred.
+ side effects - populates the $instusers and $instids refs to hashes.
+                with information for specified username, or specified
+                id, if fifth argument provided, from all available, or 
+                specified (e.g., faculty only) institutional datafeeds,
+                if sixth argument provided.
+
+ WARNING: You need to set $outcome to 'ok' once you have customized
+          this routine to communicate with an instititional 
+          directory data source, otherwise institutional directory 
+          searches will always be reported as being unavailable
+          in domain $dom.
+
+=cut
 
 sub get_userinfo {
     my ($dom,$uname,$id,$instusers,$instids,$types,
@@ -573,23 +627,25 @@
     return $outcome;
 }
 
-###############################
-# sub inst_usertypes 
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $usertypes - reference to hash which will contain 
-#                 key = value, where keys are institution 
-#                 affiliation types (e.g., Faculty, Student etc.)
-#                 and values are titles (e.g., Faculty/Academic Staff)
-# (c) $order - reference to array which will contain the order in
-#              which institutional types should be shown
-#              when displaying data tables (e.g., default quotas    
-#              or updateable user fields (see domainprefs.pm) 
-# returns 1 parameter - 'ok' if no processing error, or other value 
-#                        if an error occurred.
-#
-###############################
+=pod
+
+=item inst_usertypes() 
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $usertypes - reference to hash which will contain 
+                 key = value, where keys are institution 
+                 affiliation types (e.g., Faculty, Student etc.)
+                 and values are titles (e.g., Faculty/Academic Staff)
+ (c) $order - reference to array which will contain the order in
+              which institutional types should be shown
+              when displaying data tables (e.g., default quotas    
+              or updateable user fields (see domainprefs.pm) 
+ returns 1 parameter - 'ok' if no processing error, or other value 
+                        if an error occurred.
+
+
+=cut
 
 sub inst_usertypes {
     my ($dom,$usertypes,$order) = @_;
@@ -599,33 +655,34 @@
     return $outcome;
 }
 
-###############################
-# sub username_rules
-#
-# Incoming data: three arguments 
-# (a) $dom - domain
-# (b) $ruleshash - reference to hash containing rules
-#                  (a hash of a hash)
-#                  keys of top level hash are short names  
-#                   (e.g., netid, noncredit) 
-#                  for each key, value is a hash
-#                      desc => long name for rule  
-#                      rule => description of rule
-#                      authtype => (krb5,krb4,int, or loc)
-#                                 authentication type for rule 
-#                      authparm => authentication parameter for rule
-#                      authparmfixed => 1 if authparm used when
-#                          creating user for rule must be authparm  
-#                      authmsg => Message to display describing 
-#                                 authentication to use for this rule
-#
-# (c) $rulesorder - reference to array containing rule names 
-#                   in order to be displayed
+=pod
 
-#
-#  returns 'ok' if no processing error.
-#
-############################### 
+=item username_rules()
+
+ Incoming data: three arguments 
+ (a) $dom - domain
+ (b) $ruleshash - reference to hash containing rules
+                  (a hash of a hash)
+                  keys of top level hash are short names  
+                   (e.g., netid, noncredit) 
+                  for each key, value is a hash
+                      desc => long name for rule  
+                      rule => description of rule
+                      authtype => (krb5,krb4,int, or loc)
+                                 authentication type for rule 
+                      authparm => authentication parameter for rule
+                      authparmfixed => 1 if authparm used when
+                          creating user for rule must be authparm  
+                      authmsg => Message to display describing 
+                                 authentication to use for this rule
+
+ (c) $rulesorder - reference to array containing rule names 
+                   in order to be displayed
+
+
+  returns 'ok' if no processing error.
+
+=cut
 
 sub username_rules {
     my ($dom,$ruleshash,$rulesorder) = @_;
@@ -633,25 +690,26 @@
     return $outcome;
 }
 
-###############################
-# sub id_rules
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $ruleshash - reference to hash containing rules
-#                  (a hash of a hash)
-#                  keys of top level hash are short names
-#                   (e.g., netid, noncredit)
-#                  for each key, value is a hash
-#                      desc => long name for rule
-#                      rule => description of rule
-#
-# (c) $rulesorder - reference to array containing rule names
-#                   in order to be displayed
-#
-#  returns 'ok' if no processing error.
-#
-###############################
+=pod
+
+=item id_rules()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $ruleshash - reference to hash containing rules
+                  (a hash of a hash)
+                  keys of top level hash are short names
+                   (e.g., netid, noncredit)
+                  for each key, value is a hash
+                      desc => long name for rule
+                      rule => description of rule
+
+ (c) $rulesorder - reference to array containing rule names
+                   in order to be displayed
+
+  returns 'ok' if no processing error.
+
+=cut
 
 sub id_rules {
     my ($dom,$ruleshash,$rulesorder) = @_;
@@ -659,26 +717,27 @@
     return $outcome;
 }
 
-###############################
-# sub selfcreate_rules
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $ruleshash - reference to hash containing rules
-#                  (a hash of a hash)
-#                  keys of top level hash are short names
-#                   (e.g., netid)
-#                  for each key, value is a hash
-#                      desc => long name for rule
-#                      rule => description of rule
-#
-# (c) $rulesorder - reference to array containing rule names
-#                   in order to be displayed
-#
-#  returns 'ok' if no processing error.
-#
-###############################
+=pod
 
+=item selfcreate_rules()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $ruleshash - reference to hash containing rules
+                  (a hash of a hash)
+                  keys of top level hash are short names
+                   (e.g., netid)
+                  for each key, value is a hash
+                      desc => long name for rule
+                      rule => description of rule
+
+ (c) $rulesorder - reference to array containing rule names
+                   in order to be displayed
+
+  returns 'ok' if no processing error.
+
+
+=cut
 
 sub selfcreate_rules {
     my ($dom,$ruleshash,$rulesorder) = @_;
@@ -686,21 +745,23 @@
     return $outcome;
 }
 
-###############################
-# sub username_check 
-#
-# Incoming data: four arguments
-# (a) $dom - domain (scalar) 
-# (b) $uname - username to compare against rules (scalar)
-# (c) $to_check (reference to array of rule names to check)
-# (d) $resultshash (reference to hash of results)
-#                    hash of results for rule checked
-#                   - keys are rule names
-#                   - values are: 1 or 0 (for matched or unmatched) 
-#
-# returns 'ok' if no processing error.
-#
-###############################
+=pod
+
+=item username_check() 
+
+ Incoming data: four arguments
+ (a) $dom - domain (scalar) 
+ (b) $uname - username to compare against rules (scalar)
+ (c) $to_check (reference to array of rule names to check)
+ (d) $resultshash (reference to hash of results)
+                    hash of results for rule checked
+                   - keys are rule names
+                   - values are: 1 or 0 (for matched or unmatched) 
+
+ returns 'ok' if no processing error.
+
+
+=cut
 
 sub username_check {
     my ($dom,$uname,$to_check,$resultshash) = @_;
@@ -708,21 +769,23 @@
     return $outcome; 
 }
 
-###############################
-# sub id_check
-#
-# Incoming data: four arguments
-# (a) $dom - domain (scalar)
-# (b) $id - ID to compare against rules (scalar)
-# (c) $to_check (reference to array of rule names to check)
-# (d) $resultshash (reference to hash of results)
-#                    hash of results for rule checked
-#                   - keys are rule names
-#                   - values are: 1 or 0 (for matched or unmatched)
-#
-# returns 'ok' if no processing error.
-#
-###############################
+=pod
+
+=item id_check()
+
+ Incoming data: four arguments
+ (a) $dom - domain (scalar)
+ (b) $id - ID to compare against rules (scalar)
+ (c) $to_check (reference to array of rule names to check)
+ (d) $resultshash (reference to hash of results)
+                    hash of results for rule checked
+                   - keys are rule names
+                   - values are: 1 or 0 (for matched or unmatched)
+
+ returns 'ok' if no processing error.
+
+
+=cut
 
 sub id_check {
     my ($dom,$id,$to_check,$resultshash) = @_;
@@ -730,21 +793,23 @@
     return $outcome;
 }
 
-###############################
-# sub selfcreate_check
-#
-# Incoming data: four arguments
-# (a) $dom - domain (scalar)
-# (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)
-# (c) $to_check (reference to array of rule names to check)
-# (d) $resultshash (reference to hash of results)
-#                   hash of results for rule checked
-#                   - keys are rule names
-#                   - values are: 1 or 0 (for matched or unmatched)
-#
-# returns 'ok' if no processing error.
-#
-###############################
+=pod
+
+=item selfcreate_check()
+
+ Incoming data: four arguments
+ (a) $dom - domain (scalar)
+ (b) $selfcreatename - e-mail proposed as username (compare against rules - scalar)
+ (c) $to_check (reference to array of rule names to check)
+ (d) $resultshash (reference to hash of results)
+                   hash of results for rule checked
+                   - keys are rule names
+                   - values are: 1 or 0 (for matched or unmatched)
+
+ returns 'ok' if no processing error.
+
+
+=cut
 
 sub selfcreate_check {
     my ($dom,$selfcreatename,$to_check,$resultshash) = @_;
@@ -752,19 +817,23 @@
     return $outcome;
 }
 
-###############################
-# sub AUTOLOAD
-#
-# Incoming data: none
-# Returns ''
-#
-# Prevents errors when undefined subroutines are called in this package
-# Will allow new routines added in the future to be called from lond etc.
-# without the need for customized versions of local*.pm packages to be
-# modified to include the new subroutines immediately.
-#
-# See "Programming Perl" 3rd ed. pp 296-298.   
-###############################
+=pod
+
+=item AUTOLOAD()
+
+ Incoming data: none
+ Returns ''
+
+ Prevents errors when undefined subroutines are called in this package
+ Will allow new routines added in the future to be called from lond etc.
+ without the need for customized versions of local*.pm packages to be
+ modified to include the new subroutines immediately.
+
+ See "Programming Perl" 3rd ed. pp 296-298.   
+
+=back
+
+=cut
 
 sub AUTOLOAD {
     our $AUTOLOAD;

--jms1227618987--