From 21d7606604dab27e62ed700a39425b983901cef1 Mon Sep 17 00:00:00 2001
From: gmungoc <g.m.carstairs@dundee.ac.uk>
Date: Tue, 11 Apr 2017 11:48:40 +0100
Subject: [PATCH] JAL-2428 Javadoc

---
 src/jalview/analysis/AverageDistanceTree.java |   28 +++++++----------
 src/jalview/analysis/NJTree.java              |   41 ++++++++-----------------
 src/jalview/analysis/TreeBuilder.java         |   24 ++++++++++-----
 3 files changed, 40 insertions(+), 53 deletions(-)

diff --git a/src/jalview/analysis/AverageDistanceTree.java b/src/jalview/analysis/AverageDistanceTree.java
index 5b0e20a..907109e 100644
--- a/src/jalview/analysis/AverageDistanceTree.java
+++ b/src/jalview/analysis/AverageDistanceTree.java
@@ -5,6 +5,10 @@ import jalview.api.analysis.SimilarityParamsI;
 import jalview.datamodel.SequenceNode;
 import jalview.viewmodel.AlignmentViewport;
 
+/**
+ * This class implements distance calculations used in constructing a Average
+ * Distance tree (also known as UPGMA)
+ */
 public class AverageDistanceTree extends TreeBuilder
 {
   /**
@@ -59,10 +63,7 @@ public class AverageDistanceTree extends TreeBuilder
   }
 
   /**
-   * Returns the minimum distance between two clusters, and also sets the
-   * indices of the clusters in fields mini and minj
-   * 
-   * @return DOCUMENT ME!
+   * {@inheritDoc}
    */
   @Override
   protected double findMinDistance()
@@ -89,24 +90,17 @@ public class AverageDistanceTree extends TreeBuilder
   }
 
   /**
-   * DOCUMENT ME!
-   * 
-   * @param tmpi
-   *          DOCUMENT ME!
-   * @param tmpj
-   *          DOCUMENT ME!
-   * @param dist
-   *          DOCUMENT ME!
+   * {@inheritDoc}
    */
   @Override
-  protected void findNewDistances(SequenceNode tmpi, SequenceNode tmpj,
+  protected void findNewDistances(SequenceNode nodei, SequenceNode nodej,
           double dist)
   {
     double ih = 0;
     double jh = 0;
 
-    SequenceNode sni = tmpi;
-    SequenceNode snj = tmpj;
+    SequenceNode sni = nodei;
+    SequenceNode snj = nodej;
 
     while (sni != null)
     {
@@ -120,8 +114,8 @@ public class AverageDistanceTree extends TreeBuilder
       snj = (SequenceNode) snj.left();
     }
 
-    tmpi.dist = ((dist / 2) - ih);
-    tmpj.dist = ((dist / 2) - jh);
+    nodei.dist = ((dist / 2) - ih);
+    nodej.dist = ((dist / 2) - jh);
   }
 
 }
diff --git a/src/jalview/analysis/NJTree.java b/src/jalview/analysis/NJTree.java
index 040b7b6..487e85e 100644
--- a/src/jalview/analysis/NJTree.java
+++ b/src/jalview/analysis/NJTree.java
@@ -26,10 +26,8 @@ import jalview.datamodel.SequenceNode;
 import jalview.viewmodel.AlignmentViewport;
 
 /**
- * DOCUMENT ME!
- * 
- * @author $author$
- * @version $Revision$
+ * This class implements distance calculations used in constructing a Neighbour
+ * Joining tree
  */
 public class NJTree extends TreeBuilder
 {
@@ -49,13 +47,10 @@ public class NJTree extends TreeBuilder
   }
 
   /**
-   * DOCUMENT ME!
-   * 
-   * @return DOCUMENT ME!
+   * {@inheritDoc}
    */
   @Override
-  protected
-  double findMinDistance()
+  protected double findMinDistance()
   {
     double min = Double.MAX_VALUE;
 
@@ -83,36 +78,26 @@ public class NJTree extends TreeBuilder
   }
 
   /**
-   * DOCUMENT ME!
-   * 
-   * @param tmpi
-   *          DOCUMENT ME!
-   * @param tmpj
-   *          DOCUMENT ME!
-   * @param dist
-   *          DOCUMENT ME!
+   * {@inheritDoc}
    */
   @Override
-  protected
-  void findNewDistances(SequenceNode tmpi, SequenceNode tmpj, double dist)
+  protected void findNewDistances(SequenceNode nodei, SequenceNode nodej,
+          double dist)
   {
+    nodei.dist = ((dist + ri) - rj) / 2;
+    nodej.dist = (dist - nodei.dist);
 
-    tmpi.dist = ((dist + ri) - rj) / 2;
-    tmpj.dist = (dist - tmpi.dist);
-
-    if (tmpi.dist < 0)
+    if (nodei.dist < 0)
     {
-      tmpi.dist = 0;
+      nodei.dist = 0;
     }
 
-    if (tmpj.dist < 0)
+    if (nodej.dist < 0)
     {
-      tmpj.dist = 0;
+      nodej.dist = 0;
     }
   }
 
-
-
   /**
    * Calculates and saves the distance between the combination of cluster(i) and
    * cluster(j) and all other clusters. The new distance to cluster k is
diff --git a/src/jalview/analysis/TreeBuilder.java b/src/jalview/analysis/TreeBuilder.java
index 5347ba2..5381880 100644
--- a/src/jalview/analysis/TreeBuilder.java
+++ b/src/jalview/analysis/TreeBuilder.java
@@ -253,6 +253,12 @@ public abstract class TreeBuilder
     findMaxDist(top);
   }
 
+  /**
+   * Returns the minimum distance between two clusters, and also sets the
+   * indices of the clusters in fields mini and minj
+   * 
+   * @return
+   */
   protected abstract double findMinDistance();
 
   /**
@@ -295,10 +301,10 @@ public abstract class TreeBuilder
   }
 
   /**
-   * DOCUMENT ME!
+   * Finds the node, at or below the given node, with the maximum distance, and
+   * saves the node and the distance value
    * 
    * @param nd
-   *          DOCUMENT ME!
    */
   void findMaxDist(SequenceNode nd)
   {
@@ -325,14 +331,12 @@ public abstract class TreeBuilder
   }
 
   /**
-   * DOCUMENT ME!
+   * Calculates and returns r, whatever that is
    * 
    * @param i
-   *          DOCUMENT ME!
    * @param j
-   *          DOCUMENT ME!
    * 
-   * @return DOCUMENT ME!
+   * @return
    */
   protected double findr(int i, int j)
   {
@@ -428,8 +432,12 @@ public abstract class TreeBuilder
     done.set(j);
   }
 
-  protected abstract void findNewDistances(SequenceNode tmpi, SequenceNode tmpj,
-          double dist);
+  /*
+   * Computes and stores new distances for nodei and nodej, given the previous
+   * distance between them
+   */
+  protected abstract void findNewDistances(SequenceNode nodei,
+          SequenceNode nodej, double previousDistance);
 
   /**
    * Calculates and saves the distance between the combination of cluster(i) and
-- 
1.7.10.2