stat: improve doc comments

covariancematrix.go

@@ -12,15 +12,17 @@ import (
 	"github.com/gonum/matrix/mat64"
 )
 
-// CovarianceMatrix calculates a covariance matrix (also known as a
-// variance-covariance matrix) from a matrix of data, using a two-pass
-// algorithm.
+// CovarianceMatrix returns the covariance matrix (also known as the
+// variance-covariance matrix) calculated from a matrix of data, x, using
+// a two-pass algorithm.
 //
-// The weights must have length equal to the number of rows in
-// input data matrix x. If cov is nil, then a new matrix with appropriate size will
-// be constructed. If cov is not nil, it should have the same number of columns as the
-// input data matrix x, and it will be used as the destination for the covariance
-// data. Weights must not be negative.
+// If weights is not nil the weighted covariance of x is calculated. weights
+// must have length equal to the number of rows in input data matrix and
+// must not contain negative elements.
+// If cov is nil, a new matrix with appropriate size will be constructed.
+// If cov is not nil, it must have the same number of columns as the input
+// data matrix, and it will be used as the destination for the covariance
+// data.
 func CovarianceMatrix(cov *mat64.SymDense, x mat64.Matrix, weights []float64) *mat64.SymDense {
 	// This is the matrix version of the two-pass algorithm. It doesn't use the
 	// additional floating point error correction that the Covariance function uses
@@ -72,14 +74,16 @@ func CovarianceMatrix(cov *mat64.SymDense, x mat64.Matrix, weights []float64) *m
 	return cov
 }
 
-// CorrelationMatrix calculates a correlation matrix from a matrix of data
-// using a two-pass algorithm.
+// CorrelationMatrix returns the correlation matrix calculated from a matrix
+// of data, x, using a two-pass algorithm.
 //
-// The weights must have length equal to the number of rows in
-// input data matrix x. If corr is nil, then a new matrix with appropriate size will
-// be constructed. If corr is not nil, it should have the same number of columns
-// as the input data matrix x, and it will be used as the destination for the
-// correlation data. Weights must not be negative.
+// If weights is not nil the weighted correlation of x is calculated. weights
+// must have length equal to the number of rows in input data matrix and
+// must not contain negative elements.
+// If corr is nil, a new matrix with appropriate size will be constructed.
+// If corr is not nil, it must have the same number of columns as the input
+// data matrix, and will be used as the destination for the correlation
+// data.
 func CorrelationMatrix(corr *mat64.SymDense, x mat64.Matrix, weights []float64) *mat64.SymDense {
 	// This will panic if the sizes don't match, or if weights is the wrong size.
 	corr = CovarianceMatrix(corr, x, weights)