--- loncom/homework/response.pm	2007/05/23 22:36:21	1.167
+++ loncom/homework/response.pm	2007/05/31 04:15:52	1.168
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # various response type definitons response definition
 #
-# $Id: response.pm,v 1.167 2007/05/23 22:36:21 albertel Exp $
+# $Id: response.pm,v 1.168 2007/05/31 04:15:52 albertel Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -841,14 +841,33 @@ sub showallfoils {
     return 0;
 }
 
+=pod
+
+=item &getresponse($offset,$resulttype);
+
+Retreives the current submitted response, helps out in the case of
+scantron mode.
+
+Returns either the exact text of the submission, or a bubbled response
+converted to something usable.
+
+Optional Arguments:
+  $offset - if a problem has more than one bubble response, pass in the number
+            of the bubble wanted
+  $resulttype - undef    -> a number between 0 and 25
+                'A is 1' -> a number between 1 and 26
+                'letter' -> a letter between 'A' and 'Z'
+
+=cut
+
 sub getresponse {
-    my ($temp,$resulttype)=@_;
+    my ($offset,$resulttype)=@_;
     my $formparm='form.HWVAL_'.$Apache::inputtags::response['-1'];
     my $response;
-    if (!defined($temp)) {
+    if (!defined($offset)) {
 	$temp=1;
     } else {
-	$formparm.=":$temp";
+	$formparm.=":$offset";
     }
     my %let_to_num=('A'=>0,'B'=>1,'C'=>2,'D'=>3,'E'=>4,'F'=>5,'G'=>6,'H'=>7,
 		    'I'=>8,'J'=>9,'K'=>10,'L'=>11,'M'=>12,'N'=>13,'O'=>14,
@@ -857,7 +876,7 @@ sub getresponse {
     if ($env{'form.submitted'} eq 'scantron') {
 	my $part  = $Apache::inputtags::part;
 	my $id    = $Apache::inputtags::response[-1];
-	$response = $env{'scantron.'.($Apache::lonxml::counter+$temp-1).
+	$response = $env{'scantron.'.($Apache::lonxml::counter+$offset-1).
 			 '.answer'};
 	# save bubbled letter for later
 	$Apache::lonhomework::results{"resource.$part.$id.scantron"}.=
@@ -875,6 +894,15 @@ sub getresponse {
     return $response;
 }
 
+=pod
+
+=item &repetition();
+
+Returns the number of lines that are required to encode the weight.
+(Currently expects that there are 10 bubbles per line)
+
+=cut
+
 sub repetition {
     my $id = $Apache::inputtags::part;
     my $weight = &Apache::lonnet::EXT("resource.$id.weight");
@@ -884,6 +912,30 @@ sub repetition {
     return $repetition;
 }
 
+=pod
+
+=item &scored_response($part_id,$response_id);
+
+Sets the results hash elements
+
+   resource.$part_id.$response_id.awarded - to the floating point
+     number between 0 and 1 that was awarded on the bubbled input
+
+   resource.$part_id.$response_id.awarddetail - to 'ASSIGNED_SCORE'
+
+Returns
+
+   the number of bubble sheet lines that were used (and likely need to
+     be passed to &Apache::lonxml::increment_counter()
+
+Arguments
+
+   $part_id - id of the part to grade
+   $response_id - id of the response to grade
+  
+
+=cut
+
 sub scored_response {
     my ($part,$id)=@_;
     my $repetition=&repetition();