From 7aa1e482163172b1ea16622eb2195fc8f2039951 Mon Sep 17 00:00:00 2001
From: gmungoc <g.m.carstairs@dundee.ac.uk>
Date: Mon, 8 Oct 2018 10:13:00 +0100
Subject: [PATCH] JAL-1244 comments, javadoc, method signature tweaks

---
 src/jalview/gui/SeqPanel.java |   45 ++++++++++++++++++++++++++---------------
 1 file changed, 29 insertions(+), 16 deletions(-)

diff --git a/src/jalview/gui/SeqPanel.java b/src/jalview/gui/SeqPanel.java
index d0aa93f..87e655b 100644
--- a/src/jalview/gui/SeqPanel.java
+++ b/src/jalview/gui/SeqPanel.java
@@ -1189,7 +1189,8 @@ public class SeqPanel extends JPanel
    *          (unused parameter)
    * @param startres
    *          the column at which to perform the action; the number of columns
-   *          affected depends on <code>this.lastres</code> (cursor position)
+   *          affected depends on <code>this.editLastRes</code> (cursor column
+   *          position)
    */
   synchronized void editSequence(boolean insertGap, boolean editSeq,
           final int startres)
@@ -1241,7 +1242,11 @@ public class SeqPanel extends JPanel
       editCommand = new EditCommand(label);
     }
 
-    // Are we editing within a selection group?
+    /*
+     * is there a selection group containing the sequence being edited?
+     * if so the boundary of the group is the limit of the edit
+     * (but the edit may be inside or outside the selection group)
+     */
     boolean inSelectionGroup = sg != null
             && sg.getSequences(av.getHiddenRepSequences()).contains(seq);
     if (groupEditing || inSelectionGroup)
@@ -1314,16 +1319,16 @@ public class SeqPanel extends JPanel
       }
     }
 
-    boolean endEditing = doEditSequence(insertGap, editSeq, startres,
+    boolean success = doEditSequence(insertGap, editSeq, startres,
             fixedRight, fixedColumns, sg);
 
     /*
      * report what actually happened (might be less than
-     * what was requested), by inspecting the edit command added
+     * what was requested), by inspecting the edit commands added
      */
     String msg = getEditStatusMessage(editCommand);
     ap.alignFrame.statusBar.setText(msg == null ? " " : msg);
-    if (endEditing)
+    if (!success)
     {
       endEditing();
     }
@@ -1337,19 +1342,27 @@ public class SeqPanel extends JPanel
    * gaps (if possible). Answers true if the edit was successful, false if could
    * only be performed in part or not at all. Failure may occur in 'locked edit'
    * mode, when an insertion requires a matching gapped position (or column) to
-   * delete, and deletion requires a gapped position (or column) to remove.
+   * delete, and deletion requires an adjacent gapped position (or column) to
+   * remove.
    * 
    * @param insertGap
+   *          true if inserting gap(s), false if deleting
    * @param editSeq
+   *          (unused parameter, currently always false)
    * @param startres
+   *          the column at which to perform the edit
    * @param fixedRight
+   *          fixed right boundary column of a locked edit (within or to the
+   *          left of a selection group)
    * @param fixedColumns
+   *          true if this is a locked edit
    * @param sg
+   *          the sequence group (if group edit is being performed)
    * @return
    */
-  protected boolean doEditSequence(boolean insertGap, boolean editSeq,
-          final int startres, int fixedRight, boolean fixedColumns,
-          SequenceGroup sg)
+  protected boolean doEditSequence(final boolean insertGap,
+          final boolean editSeq, final int startres, int fixedRight,
+          final boolean fixedColumns, final SequenceGroup sg)
   {
     final SequenceI seq = av.getAlignment().getSequenceAt(editStartSeq);
     SequenceI[] seqs = new SequenceI[] { seq };
@@ -1411,7 +1424,7 @@ public class SeqPanel extends JPanel
                     && startres < av.getAlignment().getHiddenColumns()
                             .getNextHiddenBoundary(false, startres)))
             {
-              return true;
+              return false;
             }
 
             int alWidth = av.getAlignment().getWidth();
@@ -1431,7 +1444,7 @@ public class SeqPanel extends JPanel
           }
           else
           {
-            return true;
+            return false;
           }
         }
       }
@@ -1454,7 +1467,7 @@ public class SeqPanel extends JPanel
             if (!Comparison.isGap(groupSeqs[g].getCharAt(j)))
             {
               // Not a gap, block edit not valid
-              return true;
+              return false;
             }
           }
         }
@@ -1508,10 +1521,10 @@ public class SeqPanel extends JPanel
             if (!insertGap(j, seqs, fixedRight))
             {
               /*
-               * e.g. cursor mode command asked for 
+               * e.g. cursor mode command specified 
                * more inserts than are possible
                */
-              return true;
+              return false;
             }
           }
         }
@@ -1532,7 +1545,7 @@ public class SeqPanel extends JPanel
             {
               if (!Comparison.isGap(seq.getCharAt(startres)))
               {
-                return true;
+                return false;
               }
               deleteChar(startres, seqs, fixedRight);
             }
@@ -1573,7 +1586,7 @@ public class SeqPanel extends JPanel
       }
     }
 
-    return false;
+    return true;
   }
 
   /**
-- 
1.7.10.2