My current

lib/Matrix.pm

@@ -1,11 +1,17 @@
 =head1 NAME
 
-Matrix - Matrix of Reals
+lib/Matrix - Matrix of Reals
 
-Implements overrides for MatrixReal.pm for WeBWorK
 
 =head1 DESCRIPTION
 
+Implements overrides for MatrixReal.pm for WeBWorK
+In general it is better to use MathObjects Matrices (Value::Matrix)
+in writing PG problem.  The answer checking is much superior with better
+error messages for syntax errors in student entries.  Some of the 
+subroutines in this file are still used behind the scenes 
+by Value::Matrix to perform calculations,
+such as decompose_LR(). 
 
 
 =head1 SYNOPSIS
@@ -68,8 +74,22 @@ sub _stringify {
     return($s);
 }
 
+=head3 Accessor functions
+
+	(these are deprecated for direct use.  Use the covering Methods
+	 provided by MathObject Matrices instead.)
+
+	L($matrix) - return matrix L of the LR decomposition
+	R($matrix) - return matrix R of the LR decomposition
+	PL($matrix) return 
+	PR($matrix 
+
+Original matrix is  P_L * L * R *P_R
 # obtain the Left Right matrices of the decomposition and the two pivot permutation matrices
 # the original is M = PL*L*R*PR
+
+=cut 
+
 sub L {
 	my $matrix = shift;
 	my $rows = $matrix->[1];
@@ -119,10 +139,14 @@ sub PR { # use this permuation on the right PL*L*R*PR =M
 }
 # obtain the Left Right matrices of the decomposition and the two pivot permutation matrices
 # the original is M = PL*L*R*PR
-=head4
+
+
+=item	rh_options
 
 	Method $matrix->rh_options
 
+Meant for internal use when dealing with MatrixReal1
+
 =cut
 
 sub rh_options {
@@ -132,14 +156,18 @@ sub rh_options {
 	$self->[$MatrixReal1::OPTION_ENTRY];     # provides a reference to the options hash MEG
 }
 
-=head4
 
-	Method $matrix->trace
-
+=item	trace
+
+	Method: $matrix->trace
 	Returns: scalar which is the trace of the matrix.
+
+Used by MathObject Matrices for calculating the trace. 
+Deprecated for direct use in PG questions.
 
 =cut
 
+
 sub trace {
 	my $self = shift;
 	my $rows = $self->[1];
@@ -152,9 +180,12 @@ sub trace {
 	$sum;
 }
 
-=head4
 
-	Method $matrix->new_from_array_ref
+=item new_from_array_ref
+
+	Method    $new_matrix = $matrix->new_from_array_ref ([[a,b,c],[d,e,f]])
+
+Deprecated in favor of using creation tools for MathObject Matrices 
 
 =cut
 
@@ -168,21 +199,25 @@ sub new_from_array_ref {  # this will build a matrix or a row vector from  [a, b
 	$matrix;
 }
 
-=head4
+=item array_ref
 
 	Method $matrix->array_ref
 
+Converts Matrix from an ARRAY to an ARRAY reference.
+
 =cut
 
 sub array_ref {
 	my $this = shift;
 	$this->[0];
 }
 
-=head4
+=item list
 
 	Method $matrix->list
 
+Converts a Matrix column vector to an ARRAY (list).
+
 =cut
 
 sub list {           # this is used only for column vectors
@@ -196,29 +231,14 @@ sub list {           # this is used only for column vectors
 	@list;
 }
 
-=head4
-
-	Method $matrix->new_from_list
-
-=cut
-
-sub new_from_list {   # this builds a row vector from an array
-	my $class = shift;
-	my @list = @_;
-	my $cols = @list;
-	my $rows = 1;
-	my $matrix = new Matrix($rows, $cols);
-	my $i=1;
-	while(@list) {
-	    my $elem = shift(@list);
-		$matrix->assign($i++,1, $elem);
-	}
-	$matrix;
-}
 
-=head4
+=item new_row_matrix
 
 	Method $matrix->new_row_matrix
+
+Deprecated -- there are better tools for MathObject Matrices.
+
+Create a row 1 by n matrix from a list.  This subroutine appears to be broken
 
 =cut
 
@@ -236,10 +256,12 @@ sub new_row_matrix {   # this builds a row vector from an array
 	$matrix;
 }
 
-=head4
+=item proj
 
 	Method $matrix->proj
-
+	Provides behind the scenes calculations for MathObject Matrix->proj
+	Deprecated for direct use in favor of methods of MathObject matrix
+
 =cut
 
 sub proj{
@@ -248,9 +270,12 @@ sub proj{
 	$self * $self ->proj_coeff($vec);
 }
 
-=head4
+=item proj_coeff
 
 	Method $matrix->proj_coeff
+
+Provides behind the scenes calculations for MathObject Matrix->proj_coeff
+Deprecated for direct use in favor of methods of MathObject matrix
 
 =cut
 
@@ -267,10 +292,12 @@ sub proj_coeff{
 	$x_vector;
 }
 
-=head4
+=item new_column_matrix
 
 	Method $matrix->new_column_matrix
 
+Create column matrix from an ARRAY reference (list reference)
+
 =cut
 
 sub new_column_matrix {
@@ -286,13 +313,15 @@ sub new_column_matrix {
 	$matrix;
 }
 
-=head4
-
-	This method takes an array of column vectors, or an array of arrays,
-	and converts them to a matrix where each column is one of the previous
-	vectors.
+=item new_from_col_vecs
 
 	Method $matrix->new_from_col_vecs
+
+Deprecated: The tools for creating MathObjects Matrices are simpler.
+This method takes an array of column vectors, or an array of arrays,
+and converts them to a matrix where each column is one of the previous
+vectors.
+
 
 =cut
 
@@ -341,9 +370,11 @@ sub new_from_col_vecs
 
 =cut
 
-=head4
+=item cp
 
-	Method $matrix->new_from_col_vecs
+	Function: cp()
+
+Provides ability to use perl complex numbers. N
 
 =cut
 
@@ -354,7 +385,7 @@ sub cp  { # MEG  makes new copies of complex number
 	return $w;
 }
 
-=head4
+=item copy
 
 	Method $matrix->copy
 
@@ -397,7 +428,7 @@ sub copy
 
 # MEG added 6/25/03 to accomodate complex entries
 
-=head4
+=item conj
 
 	Method $matrix->conj
 
@@ -409,7 +440,7 @@ sub conj {
     $elem;
 }
 
-=head4
+=item transpose
 
 	Method $matrix->transpose
 
@@ -458,10 +489,13 @@ sub transpose
     $matrix1;
 }
 
-=head4
+=item decompose_LR
 
 	Method $matrix->decompose_LR
 
+Used by MathObjects Matrix for LR decomposition
+Deprecated for direct use in PG problems. 
+
 =cut
 
 sub decompose_LR