From 510c06b503a68cdd11bc75f6b7837fd8e92adfc5 Mon Sep 17 00:00:00 2001
From: gmungoc <g.m.carstairs@dundee.ac.uk>
Date: Fri, 23 Jan 2015 13:28:53 +0000
Subject: [PATCH] JAL-1619 javadoc/tidy

---
 src/jalview/util/MapList.java |   72 +++++++++++++++++++++++++++++------------
 1 file changed, 51 insertions(+), 21 deletions(-)

diff --git a/src/jalview/util/MapList.java b/src/jalview/util/MapList.java
index d688f23..32f0256 100644
--- a/src/jalview/util/MapList.java
+++ b/src/jalview/util/MapList.java
@@ -25,22 +25,38 @@ import java.util.Arrays;
 import java.util.List;
 
 /**
- * MapList Simple way of bijectively mapping a non-contiguous linear range to
- * another non-contiguous linear range Use at your own risk! TODO: efficient
- * implementation of private posMap method TODO: test/ensure that sense of from
- * and to ratio start position is conserved (codon start position recovery)
- * TODO: optimize to use int[][] arrays rather than vectors.
+ * A simple way of bijectively mapping a non-contiguous linear range to another
+ * non-contiguous linear range.
+ * 
+ * Use at your own risk!
+ * 
+ * TODO: efficient implementation of private posMap method
+ * 
+ * TODO: test/ensure that sense of from and to ratio start position is conserved
+ * (codon start position recovery)
  */
 public class MapList
 {
 
+  /*
+   * Subregions (base 1) described as { [start1, end1], [start2, end2], ...}
+   */
   private List<int[]> fromShifts = new ArrayList<int[]>();
 
+  /*
+   * Same format as fromShifts, for the 'mapped to' sequence
+   */
   private List<int[]> toShifts = new ArrayList<int[]>();
 
-  private int fromRatio; // number of steps in fromShifts to one toRatio unit
+  /*
+   * number of steps in fromShifts to one toRatio unit
+   */
+  private int fromRatio;
 
-  private int toRatio; // number of steps in toShifts to one fromRatio
+  /*
+   * number of steps in toShifts to one fromRatio
+   */
+  private int toRatio;
 
   /*
    * lowest and highest value in the from Map
@@ -85,14 +101,20 @@ public class MapList
   }
 
   /**
+   * Returns the flattened 'from' ranges as [start1, end1, start2, end2, ...]
    * 
-   * @return series of intervals mapped in from
+   * @return
    */
   public int[] getFromRanges()
   {
     return getRanges(fromShifts);
   }
 
+  /**
+   * Returns the flattened 'to' ranges as [start1, end1, start2, end2, ...]
+   * 
+   * @return
+   */
   public int[] getToRanges()
   {
     return getRanges(toShifts);
@@ -155,18 +177,18 @@ public class MapList
     return toHighest;
   }
 
-  private void ensureRange(int[] limits, int pos)
-  {
-    if (limits[0] > pos)
-    {
-      limits[0] = pos;
-    }
-    if (limits[1] < pos)
-    {
-      limits[1] = pos;
-    }
-  }
-
+  /**
+   * Constructor.
+   * 
+   * @param from
+   *          contiguous regions as [start1, end1, start2, end2, ...]
+   * @param to
+   *          same format as 'from'
+   * @param fromRatio
+   *          phrase length in 'from' (e.g. 3 for dna)
+   * @param toRatio
+   *          phrase length in 'to' (e.g. 1 for protein)
+   */
   public MapList(int from[], int to[], int fromRatio, int toRatio)
   {
     fromLowest = from[0];
@@ -193,8 +215,14 @@ public class MapList
     this.toRatio = toRatio;
   }
 
+  /**
+   * Copy constructor. Creates an identical mapping.
+   * 
+   * @param map
+   */
   public MapList(MapList map)
   {
+    // TODO not used - remove?
     this.fromLowest = map.fromLowest;
     this.fromHighest = map.fromHighest;
     this.toLowest = map.toLowest;
@@ -382,9 +410,10 @@ public class MapList
    * @param toRatio
    * @return
    */
-  private static int[] shift(int pos, List<int[]> shiftTo, int fromRatio,
+  protected static int[] shift(int pos, List<int[]> shiftTo, int fromRatio,
           List<int[]> shiftFrom, int toRatio)
   {
+    // TODO: javadoc; tests
     int[] fromCount = countPos(shiftTo, pos);
     if (fromCount == null)
     {
@@ -782,6 +811,7 @@ public class MapList
    */
   public boolean containsEither(boolean local, MapList map)
   {
+    // TODO not used - remove?
     if (local)
     {
       return ((getFromLowest() >= map.getFromLowest() && getFromHighest() <= map
-- 
1.7.10.2