From a4d145722369877a3cb8bfe2f23c1c405891cb6b Mon Sep 17 00:00:00 2001
From: Jim Procter <jprocter@issues.jalview.org>
Date: Tue, 13 Feb 2018 13:44:30 +0000
Subject: [PATCH] JAL-2781 tidy up comments on getMapping/computeMapping

---
 .../structure/StructureSelectionManager.java       |   43 ++++++++++++++------
 1 file changed, 31 insertions(+), 12 deletions(-)

diff --git a/src/jalview/structure/StructureSelectionManager.java b/src/jalview/structure/StructureSelectionManager.java
index 2b429d7..14cef12 100644
--- a/src/jalview/structure/StructureSelectionManager.java
+++ b/src/jalview/structure/StructureSelectionManager.java
@@ -328,22 +328,20 @@ public class StructureSelectionManager
   }
 
   /**
-   * create sequence structure mappings between each sequence and the given
-   * pdbFile (retrieved via the given protocol).
+   * Import a single structure file and register sequence structure mappings for
+   * broadcasting colouring, mouseovers and selection events (convenience
+   * wrapper).
    * 
    * @param forStructureView
    *          when true, record the mapping for use in mouseOvers
-   * 
-   * @param sequenceArray
+   * @param sequence
    *          - one or more sequences to be mapped to pdbFile
-   * @param targetChainIds
+   * @param targetChains
    *          - optional chain specification for mapping each sequence to pdb
-   *          (may be nill, individual elements may be nill) - JBPNote: JAL-2693
-   *          - this should be List<List<String>>, empty lists indicate no
-   *          predefined mappings
+   *          (may be nill, individual elements may be nill)
    * @param pdbFile
    *          - structure data resource
-   * @param sourceType
+   * @param protocol
    *          - how to resolve data from resource
    * @return null or the structure data parsed as a pdb file
    */
@@ -355,15 +353,36 @@ public class StructureSelectionManager
             pdbFile, sourceType, null);
   }
 
+  /**
+   * create sequence structure mappings between each sequence and the given
+   * pdbFile (retrieved via the given protocol). Either constructs a mapping
+   * using NW alignment or derives one from any available SIFTS mapping data.
+   * 
+   * @param forStructureView
+   *          when true, record the mapping for use in mouseOvers
+   * 
+   * @param sequenceArray
+   *          - one or more sequences to be mapped to pdbFile
+   * @param targetChainIds
+   *          - optional chain specification for mapping each sequence to pdb
+   *          (may be nill, individual elements may be nill) - JBPNote: JAL-2693
+   *          - this should be List<List<String>>, empty lists indicate no
+   *          predefined mappings
+   * @param pdbFile
+   *          - structure data resource
+   * @param sourceType
+   *          - how to resolve data from resource
+   * @param IProgressIndicator
+   *          reference to UI component that maintains a progress bar for the
+   *          mapping operation
+   * @return null or the structure data parsed as a pdb file
+   */
   synchronized public StructureFile computeMapping(
           boolean forStructureView, SequenceI[] sequenceArray,
           String[] targetChainIds, String pdbFile, DataSourceType sourceType,
           IProgressIndicator progress)
   {
     long progressSessionId = System.currentTimeMillis() * 3;
-    /*
-     * There will be better ways of doing this in the future, for now we'll use
-     * the tried and tested MCview pdb mapping
      */
     boolean parseSecStr = processSecondaryStructure;
     if (isPDBFileRegistered(pdbFile))
-- 
1.7.10.2