Merge pull request #1272 from Alex-Jordan/restructure-pod-macros-answers

Restructire the POD of macros (answers)

Author: drgrice1

macros/answers/ConditionalHint.pl

@@ -1,12 +1,10 @@
 
-=head1 ConditionalHint.pl
+=head1 NAME
 
-=head2 NAME
-
-C<ConditionalHint.pl> - Allows a hint to be revealed after a student
+ConditionalHint.pl - Allows a hint to be revealed after a student
 has entered an answer correctly.
 
-=head2 DESCRIPTION
+=head1 DESCRIPTION
 
 The subroutine C<ConditionalHint()> allows a hint to be revealed
 after a student has entered an answer correctly.  It is useful
@@ -17,9 +15,9 @@ =head2 DESCRIPTION
 A subroutine C<IsAnswerCorrect()> that returns 0 or 1 is also
 provided.
 
-=head2 USAGE
+=head1 FUNCTIONS
 
-=head3 Synopsis of ConditionalHint
+=head2 ConditionalHint
 
     loadMacros("ConditionalHint.pl");
 
@@ -102,10 +100,6 @@ =head3 Complete Working Example of ConditionalHint
 
     ENDDOCUMENT();
 
-=head2 AUTHOR
-
-Paul Pearson
-
 =cut
 
 sub _ConditionalHint_init { };    # don't reload this file
@@ -142,14 +136,8 @@ sub IsAnswerCorrect {
 		@_
 	);
 
-	#  my $name_of_correct_answer = shift;
-	#  my $answer_rule_number = shift;
-
-	#  return $name_of_correct_answer->cmp()->evaluate($inputs_ref->{ANS_NUM_TO_NAME($answer_rule_number)})->{score};
-
 	return $options{ans_name}->cmp()->evaluate($inputs_ref->{ ANS_NUM_TO_NAME($options{ans_number}) })->{score};
 
 }
 
 1;
-

macros/answers/Generic.pl

@@ -1,30 +1,28 @@
-#R. Byerly, Texas Tech University, 2005
 
-sub _Generic { }    #Don't reload this file.
+=head1 NAME
 
-#Documentation:
+Generic.pl - Provide some generic answer checkers.
 
-=head1 Generic Answer Checker
+=head1 DESCRIPTION
 
-(Based on David Cervone's vector_cmp.  See
-doc/parser/extensions/8-answer.pg under the webwork2 directory.)
-Place in macros directory and load this file (Generic.pl) using the
-loadMacros command.  (To just copy it into a pg file, replace
-occurences of "\&" by "~~&".)
+This macro provides a set of functions that provide a generic answer checker.
 
- Usage:
+Usage:
+
+    ANS(  generic_cmp(<prof_answer>, <optional and mandatory arguments>) );
 
-  ANS(  generic_cmp(<prof_answer>, <optional and mandatory arguments>) );
 where <prof_answer> is a parser object or syntactically correct string
 for a parser object.
 
 Mandatory arguments:
 
-  type => <type>
+    type => <type>
+
 where <type> is a recognized parser type (e.g., Number, Point, Vector,
 Matrix, etc.)
 
-  checker => <checker>
+    checker => <checker>
+
 where <checker> is a reference to a subroutine that will be passed (in
 order) the parsed (and, if possible, evaluated) student answer, the
 parsed professor's answer, and a reference to the answer hash.  (The
@@ -33,62 +31,55 @@ =head1 Generic Answer Checker
 
 Optional arguments:
 
- correct_ans => <answer_string>
+    correct_ans => <answer_string>
+
 where <answer_string> is a string that will show up as the correct
 answer when solutions are available.
 
- variables_allowed => 0 or 1 
+    variables_allowed => 0 or 1
+
 (default 0 (false).  Determines whether student's answer is allowed to
 contain variables.  In this case the checker must take care of
 evaluating it.)
 
- length => n
+    length => n
+
 where n is the number of elements in an expected answer of type list,
 vector, or points.  Returns error message to student if answer of wrong
 length is entered.
 
+=head1 SYNOPSIS
 
-####################Example:##########################
-DOCUMENT();        # This should be the first executable line in the problem.
+    DOCUMENT();
 
-loadMacros(
-"PG.pl",
-"PGbasicmacros.pl",
-"PGanswermacros.pl",
-"Parser.pl",
-"Generic.pl",
-);
+    loadMacros("PG.pl", "PGbasicmacros.pl", "PGanswermacros.pl", "Parser.pl", "Generic.pl");
 
-TEXT(&beginproblem);
+    Context("Vector");
+    $A=Vector(1,2,1);
+    $B=Vector(1,3,1);
+    $C=Vector(1,4,1);
 
-Context("Vector");
-$A=Vector(1,2,1);
-$B=Vector(1,3,1);
-$C=Vector(1,4,1);
+    BEGIN_TEXT
+    Show that the vectors \(\{$A->TeX\}, \{$B->TeX\}, \{$C->TeX\}\) do
+    not span \(R^3\) by giving a vector not in their span:
+    \{ans_rule()\}
+    END_TEXT
 
-BEGIN_TEXT
-Show that the vectors \(\{$A->TeX\}, \{$B->TeX\}, \{$C->TeX\}\) do
-not span \(R^3\) by giving a vector not in their span:
-\{ans_rule()\}
-END_TEXT
+    sub check {
+      my $stu=shift;
+      $x1=$stu->extract(1); $x3=$stu->extract(3);
+      $x1 != $x3; #any vectors with different 1st and 3rd coordinates
+    }
 
-#Easy to get by guessing!
-
-sub check{
-  my $stu=shift();
-  $x1=$stu->extract(1); $x3=$stu->extract(3);
-  $x1 != $x3; #any vectors with different 1st and 3rd coordinates
-}
+    ANS(generic_cmp("23",type => 'Vector', length => 3, checker => ~~&check));
 
-ANS(generic_cmp("23",type => 'Vector', length => 3, checker => ~~&check));
+    ENDDOCUMENT();
 
-ENDDOCUMENT(); # This should be the last executable line in the problem.
-
-####################End of Example########################
+=head1 FUNCTIONS
 
 =cut
 
-#End of Documentation
+sub _Generic_init { }    # don't reload this file.
 
 #From parserUtils.pl:
 sub protectHTML {
@@ -100,6 +91,10 @@ sub protectHTML {
 
 }
 
+=head2 generic_cmp
+
+=cut
+
 sub generic_cmp {
 	my $v    = shift;
 	my %opts = @_;
@@ -120,6 +115,10 @@ sub generic_cmp {
 	return $ans;
 }
 
+=head2 generic_cmp_check
+
+=cut
+
 sub generic_cmp_check {
 	my $ans  = shift;
 	my $type = $ans->{type};