From eae889570267900d7d583611b0a6d45c343bb88e Mon Sep 17 00:00:00 2001
From: veillettem <martin.veillette@gmail.com>
Date: Tue, 28 Jun 2016 11:35:27 -0400
Subject: [PATCH] add JSDOC to eigenvalueDecomposition  (see #49)

---
 js/EigenvalueDecomposition.js | 62 ++++++++++++++++++++++++++++-------
 1 file changed, 50 insertions(+), 12 deletions(-)

diff --git a/js/EigenvalueDecomposition.js b/js/EigenvalueDecomposition.js
index 9e043cb..ccbea5d 100644
--- a/js/EigenvalueDecomposition.js
+++ b/js/EigenvalueDecomposition.js
@@ -30,18 +30,23 @@ define( function( require ) {
 
   // require( 'DOT/Matrix' ); // commented out so Require.js doesn't complain about the circular dependency
 
+  /**
+   *
+   * @param {Matrix} matrix - must be a square matrix
+   * @constructor
+   */
   function EigenvalueDecomposition( matrix ) {
     var i;
     var j;
 
     var A = matrix.entries;
-    this.n = matrix.getColumnDimension(); // Row and column dimension (square matrix).
+    this.n = matrix.getColumnDimension(); // @private  Row and column dimension (square matrix).
     var n = this.n;
-    this.V = new ArrayType( n * n ); // Array for internal storage of eigenvectors.
+    this.V = new ArrayType( n * n ); // @private Array for internal storage of eigenvectors.
 
     // Arrays for internal storage of eigenvalues.
-    this.d = new ArrayType( n );
-    this.e = new ArrayType( n );
+    this.d = new ArrayType( n ); // @private
+    this.e = new ArrayType( n ); // @private
 
     this.issymmetric = true;
     for ( j = 0; (j < n) && this.issymmetric; j++ ) {
@@ -87,22 +92,38 @@ define( function( require ) {
   EigenvalueDecomposition.prototype = {
     constructor: EigenvalueDecomposition,
 
-    // Return the eigenvector matrix
+    /**
+     * Returns a square array of all eigenvectors arranged in a columnar format
+     * @public
+     * @returns {ArrayType.<number>} - a n*n matrix
+     */
     getV: function() {
       return this.V.copy();
     },
 
-    // {Array} Return the real parts of the eigenvalues
+    /**
+     * Returns an array that contains the real part of the eigenvalues
+     * @public
+     * @returns {ArrayType.<number>} - a one dimensional array
+     */
     getRealEigenvalues: function() {
       return this.d;
     },
 
-    // {Array} Return the imaginary parts of the eigenvalues
+    /**
+     * Returns an array that contains the imaginary parts of the eigenvalues
+     * @public
+     * @returns {ArrayType.<number>} - a one dimensional array
+     */
     getImagEigenvalues: function() {
       return this.e;
     },
 
-    // Return the block diagonal eigenvalue matrix
+    /**
+     * Return the block diagonal eigenvalue matrix
+     * @public
+     * @returns {Matrix} - a n * n matrix
+     */
     getD: function() {
       var n = this.n;
       var d = this.d;
@@ -125,7 +146,10 @@ define( function( require ) {
       return X;
     },
 
-    // Symmetric Householder reduction to tridiagonal form.
+    /**
+     * Symmetric Householder reduction to tridiagonal form.
+     * @private
+     */
     tred2: function() {
       var n = this.n;
       var V = this.V;
@@ -252,7 +276,10 @@ define( function( require ) {
       e[ 0 ] = 0.0;
     },
 
-    // Symmetric tridiagonal QL algorithm.
+    /**
+     * Symmetric tridiagonal QL algorithm.
+     * @private
+     */
     tql2: function() {
       var n = this.n;
       var V = this.V;
@@ -382,7 +409,10 @@ define( function( require ) {
       }
     },
 
-    // Nonsymmetric reduction to Hessenberg form.
+    /**
+     *  Nonsymmetric reduction to Hessenberg form.
+     *  @private
+     */
     orthes: function() {
       var n = this.n;
       var V = this.V;
@@ -501,7 +531,15 @@ define( function( require ) {
       }
     },
 
-    // Nonsymmetric reduction from Hessenberg to real Schur form.
+    /**
+     * This methods finds the eigenvalues and eigenvectors
+     * of a real upper hessenberg matrix by the QR algorithm
+     *
+     * Nonsymmetric reduction from Hessenberg to real Schur form.
+     * https://en.wikipedia.org/wiki/QR_algorithm
+     *
+     * @private
+     */
     hqr2: function() {
       var n;
       var V = this.V;