--- loncom/interface/lonparmset.pm	2016/07/15 18:03:52	1.561
+++ loncom/interface/lonparmset.pm	2016/07/15 22:24:37	1.562
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Handler to set parameters for assessments
 #
-# $Id: lonparmset.pm,v 1.561 2016/07/15 18:03:52 damieng Exp $
+# $Id: lonparmset.pm,v 1.562 2016/07/15 22:24:37 damieng Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -1065,16 +1065,16 @@ sub page_js {
             document.parmform.action+='#'+document.parmform.pres_marker.value;
             var typedef=new Array();
             typedef=document.parmform.pres_type.value.split('_');
-           if (document.parmform.pres_type.value!='') {
-            if (typedef[0]=='date') {
-                eval('document.parmform.recent_'+
-                     document.parmform.pres_type.value+
-             '.value=document.parmform.pres_value.value;');
-            } else {
-                eval('document.parmform.recent_'+typedef[0]+
-             '.value=document.parmform.pres_value.value;');
+            if (document.parmform.pres_type.value!='') {
+                if (typedef[0]=='date') {
+                    eval('document.parmform.recent_'+
+                        document.parmform.pres_type.value+
+                        '.value=document.parmform.pres_value.value;');
+                } else {
+                    eval('document.parmform.recent_'+typedef[0]+
+                        '.value=document.parmform.pres_value.value;');
+                }
             }
-       }
             document.parmform.submit();
         } else {
             document.parmform.pres_value.value='';
@@ -1648,7 +1648,21 @@ sub parm_control_group {
 
 
 
-# extracts lots of information about all of the the course's resources into a variety of hashes.
+# Extracts lots of information about all of the the course's resources into a variety of hashes, using lonnavmaps and lonnet::metadata.
+# All the parameters are references and are filled by the sub.
+#
+# @param {array reference} $ids - resource ids
+# @param {hash reference} $typep - hash resource id (from big hash) -> resource type (file extension)
+# @param {hash reference} $keyp - hash resource id -> comma-separated list of parameter keys from lonnet::metadata
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {hash reference} $allparts - hash parameter part -> part title (a parameter part can be problem part.'_'.response id for response parameters)
+# @param {hash reference} $allmaps - hash map id (from big hash) -> map src
+# @param {hash reference} $mapp - hash resource id -> enclosing map src
+# @param {hash reference} $symbp - hash map id or resource id -> map src.'___(all)' for a map or resource symb for a resource
+# @param {hash reference} $maptitles - hash map id or src -> map title (this should really be two separate hashes)
+# @param {hash reference} $uris - hash resource id -> resource src
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank for this parameter when looking through every resource and every parameter, starting at 100 (integer)
+# @param {hash reference} $defkeytype - hash parameter name -> parameter type
 sub extractResourceInformation {
     my $ids = shift;
     my $typep = shift;
@@ -1749,17 +1763,22 @@ sub extractResourceInformation {
 }
 
 
-
+# Tells if a parameter type is a date.
+#
+# @param {string} type - parameter type
+# @returns{boolean} - true if it is a date
 sub isdateparm {
     my $type=shift;
     return (($type=~/^date/) && (!($type eq 'date_interval')));
 }
 
+# Prints the HTML and Javascript to select parameters, with various shortcuts.
+# FIXME: remove unused parameters
 #
-# parmmenu displays a list of the selected parameters.
-# It also offers a link to show/hide the complete parameter list
-# from which you can select all desired parameters.
-#
+# @param {Apache2::RequestRec} $r - the Apache request (unused)
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {array reference} $pscat - list of selected parameter names (unused)
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank (unused)
 sub parmmenu {
     my ($r,$allparms,$pscat,$keyorder)=@_;
     my $tempkey;
@@ -1775,7 +1794,7 @@ sub parmmenu {
             displayOverview = "none"
         }
 
-    for (i=0; i<document.forms.parmform.elements.length; i++) {
+        for (i=0; i<document.forms.parmform.elements.length; i++) {
             ele = document.forms.parmform.elements[i];
             if (ele.name == checkName) {
                 document.forms.parmform.elements[i].checked=value;
@@ -1784,56 +1803,54 @@ sub parmmenu {
     }
 
     function checkthis(thisvalue, checkName) {
-
-
-    for (i=0; i<document.forms.parmform.elements.length; i++) {
+        for (i=0; i<document.forms.parmform.elements.length; i++) {
             ele = document.forms.parmform.elements[i];
             if (ele.name == checkName) {
-        if (ele.value == thisvalue) {
-            document.forms.parmform.elements[i].checked=true;
-        }
+                if (ele.value == thisvalue) {
+                    document.forms.parmform.elements[i].checked=true;
+                }
             }
         }
     }
 
     function checkdates() {
-    checkthis('duedate','pscat');
-     checkthis('opendate','pscat');
-    checkthis('answerdate','pscat');
+        checkthis('duedate','pscat');
+        checkthis('opendate','pscat');
+        checkthis('answerdate','pscat');
     }
 
     function checkdisset() {
-     checkthis('discussend','pscat');
-     checkthis('discusshide','pscat');
-     checkthis('discussvote','pscat');
+        checkthis('discussend','pscat');
+        checkthis('discusshide','pscat');
+        checkthis('discussvote','pscat');
     }
 
     function checkcontdates() {
-    checkthis('contentopen','pscat');
-     checkthis('contentclose','pscat');
+        checkthis('contentopen','pscat');
+        checkthis('contentclose','pscat');
     }
 
     function checkvisi() {
-    checkthis('hiddenresource','pscat');
-     checkthis('encrypturl','pscat');
-    checkthis('problemstatus','pscat');
-    checkthis('contentopen','pscat');
-    checkthis('opendate','pscat');
+        checkthis('hiddenresource','pscat');
+        checkthis('encrypturl','pscat');
+        checkthis('problemstatus','pscat');
+        checkthis('contentopen','pscat');
+        checkthis('opendate','pscat');
     }
 
     function checkparts() {
-    checkthis('hiddenparts','pscat');
-    checkthis('display','pscat');
-    checkthis('ordered','pscat');
+        checkthis('hiddenparts','pscat');
+        checkthis('display','pscat');
+        checkthis('ordered','pscat');
     }
 
     function checkstandard() {
         checkall(false,'pscat');
-    checkdates();
-    checkthis('weight','pscat');
-    checkthis('maxtries','pscat');
-    checkthis('type','pscat');
-    checkthis('problemstatus','pscat');
+        checkdates();
+        checkthis('weight','pscat');
+        checkthis('maxtries','pscat');
+        checkthis('type','pscat');
+        checkthis('problemstatus','pscat');
     }
 
 // ]]>
@@ -1844,7 +1861,10 @@ ENDSCRIPT
     &shortCuts($r,$allparms,$pscat,$keyorder);
     $r->print('<hr />');
 }
-# return a hash
+
+# Returns parameter categories.
+#
+# @returns {hash} - category name -> title in English
 sub categories {
     return ('time_settings' => 'Time Settings',
     'grading' => 'Grading',
@@ -1858,7 +1878,9 @@ sub categories {
     'misc' => 'Miscellaneous' ); 
 }
 
-# return a hash. Like a look-up table
+# Returns the category for each parameter.
+#
+# @returns {hash} - parameter name -> category name
 sub lookUpTableParameter {
  
     return ( 
@@ -1909,6 +1931,10 @@ sub lookUpTableParameter {
     );    
 }
 
+# Adds the given parameter name to an array of arrays listing all parameters for each category.
+#
+# @param {string} $name - parameter name
+# @param {array reference} $catList - array reference category name -> array reference of parameter names
 sub whatIsMyCategory {
     my $name = shift;
     my $catList = shift;
@@ -1932,6 +1958,11 @@ sub whatIsMyCategory {
     }        
 }
 
+# Sorts parameter names based on appearance order.
+#
+# @param {array reference} name - array reference of parameter names
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @returns {Array} - array of parameter names
 sub keysindisplayorderCategory {
     my ($name,$keyorder)=@_;
     return sort {
@@ -1939,6 +1970,9 @@ sub keysindisplayorderCategory {
     } ( @{$name});
 }
 
+# Returns a hash category name -> order, starting at 1 (integer)
+#
+# @returns {hash}
 sub category_order {
     return (
         'time_settings' => 1,
@@ -1955,6 +1989,12 @@ sub category_order {
 
 }
 
+# Prints HTML to let the user select parameters, from a list of all parameters organized by category.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {array reference} $pscat - list of selected parameter names
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
 sub parmboxes {
     my ($r,$allparms,$pscat,$keyorder)=@_;
     my %categories = &categories();
@@ -1996,9 +2036,14 @@ sub parmboxes {
     }
     $r->print("\n");
 }
+
+# Prints HTML with shortcuts to select groups of parameters in one click, or deselect all.
+# FIXME: remove unused parameters
 #
-# This function offers some links on the parameter section to get with one click a group a parameters
-#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparms - hash parameter name -> parameter title (unused)
+# @param {array reference} $pscat - list of selected parameter names (unused)
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank (unused)
 sub shortCuts {
     my ($r,$allparms,$pscat,$keyorder)=@_;
 
@@ -2031,6 +2076,12 @@ sub shortCuts {
     );
 }
 
+# Prints HTML to select parts to view (except for the title).
+# Used by table and overview modes.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparts - hash parameter part -> part title
+# @param {array reference} $psprt - list of selected parameter parts
 sub partmenu {
     my ($r,$allparts,$psprt)=@_;
     my $selsize = 1+scalar(keys(%{$allparts}));
@@ -2040,7 +2091,7 @@ sub partmenu {
 
     $r->print('<select multiple="multiple" name="psprt" size="'.$selsize.'">');
     $r->print('<option value="all"');
-    $r->print(' selected="selected"') unless (@{$psprt});
+    $r->print(' selected="selected"') unless (@{$psprt}); # useless, the array is never empty
     $r->print('>'.&mt('All Parts').'</option>');
     my %temphash=();
     foreach (@{$psprt}) { $temphash{$_}=1; }
@@ -2058,6 +2109,18 @@ sub partmenu {
     $r->print('</select>');
 }
 
+# Prints HTML to select a user and/or a group.
+# Used by table mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {string} $uname - selected user name
+# @param {string} $id - selected Student/Employee ID
+# @param {string} $udom - selected user domain
+# @param {string} $csec - selected section name
+# @param {string} $cgroup - selected group name
+# @param {string} $parmlev - parameter level (Resource:'full', Map:'map', Course:'general')
+# @param {array reference} $usersgroups - list of groups the user belongs to, if any
+# @param {string} $pssymb - resource symb (when a single resource is selected)
 sub usermenu {
     my ($r,$uname,$id,$udom,$csec,$cgroup,$parmlev,$usersgroups,$pssymb)=@_;
     my $chooseopt=&Apache::loncommon::select_dom_form($udom,'udom').' '.
@@ -2168,16 +2231,23 @@ function group_or_section(caller) {
                  ,$chooseopt));
 }
 
+# Prints HTML to select parameters from a list of all parameters.
+# Uses parmmenu and parmboxes.
+# Used by table and overview modes.
 #
-# This function shows on table Mode the available Parameters for the selected Resources
-#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allparms - hash parameter name -> parameter title
+# @param {array reference} $pscat - list of selected parameter names
+# @param {array reference} $psprt - list of selected parameter parts (unused)
+# @param {hash reference} $keyorder - hash parameter key -> appearance rank
+# @param {string} [$divid] - name used to give an id to the HTML element for the scroll box
 sub displaymenu {
     my ($r,$allparms,$pscat,$psprt,$keyorder,$divid)=@_;
 
     $r->print(&Apache::lonhtmlcommon::start_pick_box());
     $r->print(&Apache::lonhtmlcommon::row_title(&mt('Select Parameters to View')));
 
-    &parmmenu($r,$allparms,$pscat,$keyorder);
+    &parmmenu($r,$allparms,$pscat,$keyorder); # only $allparms is used by parmmenu
     $r->print(&Apache::loncommon::start_scrollbox('480px','440px','200px',$divid));
     &parmboxes($r,$allparms,$pscat,$keyorder);
     $r->print(&Apache::loncommon::end_scrollbox());
@@ -2187,6 +2257,14 @@ sub displaymenu {
  
 }
 
+# Prints HTML to select a map.
+# Used by table mode and overview mode.
+#
+# @param {Apache2::RequestRec} $r - the Apache request
+# @param {hash reference} $allmaps - hash map id -> map src
+# @param {string} $pschp - selected map id, or 'all'
+# @param {hash reference} $maptitles - hash map id or src -> map title
+# @param {hash reference} $symbp - hash map id or resource id -> map src.'___(all)' for a map or resource symb for a resource
 sub mapmenu {
     my ($r,$allmaps,$pschp,$maptitles,$symbp)=@_;
     my %allmaps_inverted = reverse %$allmaps;
@@ -2834,8 +2912,8 @@ sub assessparms {
 <script type="text/javascript">
 // <![CDATA[
 function parmsel_show() {
-  document.getElementById('parmsel').style.display = "";
-  document.getElementById('parmsellink').style.display = "none";
+    document.getElementById('parmsel').style.display = "";
+    document.getElementById('parmsellink').style.display = "none";
 }
 // ]]>
 </script>
@@ -4533,7 +4611,7 @@ ENDOVER
 
     $r->print('<div class="LC_Box">');
     $r->print('<div>');
-    &displaymenu($r,\%allparms,\@pscat,\%keyorder);
+    &displaymenu($r,\%allparms,\@pscat,\%keyorder); # FIXME: wrong parameters, could make keysindisplayorderCategory crash because $keyorder is undefined
     $r->print(&Apache::lonhtmlcommon::start_pick_box());
     $r->print(&Apache::lonhtmlcommon::row_title(&mt('Select Parts to View')));
     my $sectionselector = &sectionmenu(\@selected_sections);