--- loncom/homework/radiobuttonresponse.pm	2007/06/29 12:49:10	1.121
+++ loncom/homework/radiobuttonresponse.pm	2007/06/29 17:24:03	1.122
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # mutliple choice style responses
 #
-# $Id: radiobuttonresponse.pm,v 1.121 2007/06/29 12:49:10 foxr Exp $
+# $Id: radiobuttonresponse.pm,v 1.122 2007/06/29 17:24:03 albertel Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -232,7 +232,7 @@ sub end_foilgroup {
 						 '-2');
 	    my $randomize = &Apache::lonxml::get_param('randomize',$parstack,
 						       $safeeval,'-2');
-	    my @shown = &whichfoils($max,$randomize);
+	    my ($answer,@shown) = &whichfoils($max,$randomize);
 	    $answer_count = scalar(@shown);
 
 	    if ($target eq 'web' || $target eq 'tex') {
@@ -378,6 +378,30 @@ sub displayallfoils {
     return $result;
 }
 
+=pod
+
+=item &whichfoils($max,$randomize)
+
+Randomizes the list of foils.
+Respects
+  - each foils desire to be randomized
+  - the existance of Concept groups of foils (select 1 foil from each)
+  - and selects a single correct statement from all possilble true statments
+  - and limits it to a toal of $max foils
+
+Arguments
+  $max - maximum number of foils to select (including the true one)
+         (so a max of 5 is: 1 true, 4 false)
+
+  $randomize - whether to randomize the listing of foils, by default
+               will randomize, only if randomize is 'no' will it not
+
+Returns
+  $answer - location in the array of the correct answer
+  @foils  - array of foil names in to display order
+
+=cut
+
 sub whichfoils {
     my ($max,$randomize)=@_;