From fcd1956579a9ecf87f659096bcf6e17975c10193 Mon Sep 17 00:00:00 2001
From: kiramt <k.mourao@dundee.ac.uk>
Date: Mon, 15 Jan 2018 09:57:22 +0000
Subject: [PATCH] JAL-2759 Tidy up javadoc and naming in HiddenColumnsCursor
 after review

---
 src/jalview/datamodel/HiddenColumns.java           |    2 +-
 src/jalview/datamodel/HiddenColumnsCursor.java     |   23 +++++++++++---------
 .../jalview/datamodel/HiddenColumnsCursorTest.java |   14 ++++++------
 3 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/src/jalview/datamodel/HiddenColumns.java b/src/jalview/datamodel/HiddenColumns.java
index 6a2ca1d..e047ef4 100644
--- a/src/jalview/datamodel/HiddenColumns.java
+++ b/src/jalview/datamodel/HiddenColumns.java
@@ -744,7 +744,7 @@ public class HiddenColumns
 
       if (hiddenColumns != null)
       {
-        result += cursor.getHiddenOffset(column).getHiddenSoFar();
+        result += cursor.findRegionForVisColumn(column).getHiddenSoFar();
       }
 
       return result;
diff --git a/src/jalview/datamodel/HiddenColumnsCursor.java b/src/jalview/datamodel/HiddenColumnsCursor.java
index 3d82ee7..0fef622 100644
--- a/src/jalview/datamodel/HiddenColumnsCursor.java
+++ b/src/jalview/datamodel/HiddenColumnsCursor.java
@@ -116,14 +116,17 @@ public class HiddenColumnsCursor
   }
 
   /**
-   * Get the index of the region that column is within (if column is hidden) or
-   * which is to the right of column (if column is visible). If no hidden
-   * columns are to the right, will return size of hiddenColumns. If hidden
-   * columns is empty returns -1.
+   * Get the cursor pointing to the hidden region that column is within (if
+   * column is hidden) or which is to the right of column (if column is
+   * visible). If no hidden columns are to the right, returns a cursor pointing
+   * to an imaginary hidden region beyond the end of the hidden columns
+   * collection (this ensures the count of previous hidden columns is correct).
+   * If hidden columns is empty returns null.
    * 
    * @param column
    *          absolute position of a column in the alignment
-   * @return region index
+   * @return cursor pointing to hidden region containing the column (if hidden)
+   *         or to the right of the column (if visible)
    */
   protected HiddenCursorPosition findRegionForColumn(int column)
   {
@@ -190,14 +193,14 @@ public class HiddenColumnsCursor
   }
 
   /**
-   * Get the number of hidden columns in regions before column i.e. excludes
-   * hidden columns in the region column is in, if any
+   * Get the cursor pointing to the hidden region just after a visible column
    * 
    * @param column
-   *          index of column in visible alignment
-   * @return
+   *          index of column in *visible* alignment (therefore by definition
+   *          column is visible)
+   * @return cursor pointing to hidden region to the right of the column
    */
-  protected HiddenCursorPosition getHiddenOffset(int column)
+  protected HiddenCursorPosition findRegionForVisColumn(int column)
   {
     if (hiddenColumns == null)
     {
diff --git a/test/jalview/datamodel/HiddenColumnsCursorTest.java b/test/jalview/datamodel/HiddenColumnsCursorTest.java
index 8666bbc..257ea95 100644
--- a/test/jalview/datamodel/HiddenColumnsCursorTest.java
+++ b/test/jalview/datamodel/HiddenColumnsCursorTest.java
@@ -94,7 +94,7 @@ public class HiddenColumnsCursorTest
   {
     HiddenColumnsCursor cursor = new HiddenColumnsCursor();
 
-    HiddenCursorPosition pos = cursor.getHiddenOffset(20);
+    HiddenCursorPosition pos = cursor.findRegionForVisColumn(20);
     assertNull(pos);
 
     List<int[]> hidden = new ArrayList<>();
@@ -102,22 +102,22 @@ public class HiddenColumnsCursorTest
     hidden.add(new int[] { 104, 125 });
     cursor.resetCursor(hidden);
 
-    int offset = cursor.getHiddenOffset(80).getHiddenSoFar();
+    int offset = cursor.findRegionForVisColumn(80).getHiddenSoFar();
     assertEquals(46, offset);
 
-    offset = cursor.getHiddenOffset(79).getHiddenSoFar();
+    offset = cursor.findRegionForVisColumn(79).getHiddenSoFar();
     assertEquals(24, offset);
 
-    offset = cursor.getHiddenOffset(53).getHiddenSoFar();
+    offset = cursor.findRegionForVisColumn(53).getHiddenSoFar();
     assertEquals(24, offset);
 
-    offset = cursor.getHiddenOffset(52).getHiddenSoFar();
+    offset = cursor.findRegionForVisColumn(52).getHiddenSoFar();
     assertEquals(0, offset);
 
-    offset = cursor.getHiddenOffset(10).getHiddenSoFar();
+    offset = cursor.findRegionForVisColumn(10).getHiddenSoFar();
     assertEquals(0, offset);
 
-    offset = cursor.getHiddenOffset(0).getHiddenSoFar();
+    offset = cursor.findRegionForVisColumn(0).getHiddenSoFar();
     assertEquals(0, offset);
   }
 
-- 
1.7.10.2