Optimize path searching a bit, avoiding visiting multiple times the same macrostate to search for a path

src/main/java/info/hkzlab/dupal/analyzer/board/boardio/DuPALAnalyzer.java

@@ -330,7 +330,10 @@ public class DuPALAnalyzer {
         MacroState curMS = start;
         msSet.add(start);
 
+        // We'll search for a path of links that join "start" and "dest"
         while(curMS != null) {
+            // The current state we're in is equal to "dest", it means we've found a path!
+            // Convert the stack of links we followed into an array and return it
             if(curMS.equals(dest)) {
                 StateLink[] arr = slStack.toArray(new StateLink[slStack.size()]);
 
@@ -342,6 +345,9 @@ public class DuPALAnalyzer {
                 return arr;
             }
 
+            // We're still not at our destination, so check every link we have not yet visited in the current macrostate,
+            // and if it ends up in a state we've not yet examined, push the link into the stack, mark that state as visited 
+            // and set it as the next current one to examine to search for a path
             boolean foundLink = false;
             for(int idx = 0; idx < curMS.links.length; idx++) {
                 if((curMS.links[idx] != null) && !slSet.contains(curMS.links[idx])) { // We have not yet tried this link
@@ -355,22 +361,25 @@ public class DuPALAnalyzer {
                         foundLink = true;
                         
                         break; // Break out of this loop
+                    } else { // The MacroState has been visited already, which means that all its links were explored and deemed unsuitable
+                        logger.debug("MacroState ["+curMS.links[idx].destMS+"] has been visited previously, so we can skip it.");
                     }
                 }
             }
 
-            // Aleady searched through all this state
+            // Aleady searched through all this state, we found no link to follow
+            // So, if the stack of links we followed contains an element (which means we moved at least one place through the graph)
+            // then pop this link from the stack and go back to the previous node, so we can continue searching for a path
             if(!foundLink) {
                 if(slStack.size() > 0) {
-                    msSet.remove(slStack.pop().destMS); // Remove the last link we followed and remove the macrostate from nodes we visited
+                    slStack.pop(); // Remove the last link, the last macrostate will remain in the list of nodes we visited, so we won't search it twice
                     if(slStack.size() > 0) {
                         curMS = slStack.peek().destMS; // Back to the previous node
-                    } else curMS = start; // Back at the beginning it seems...
+                    } else curMS = start; // We ended up back at the beginning
                     logger.trace("Moved back to ["+curMS+"]");
-
-                } else {
-                    logger.info("Found no possible path out of [" + start + "] to another unvisited link.");
-                    return null;  // Found no possible path
+                } else { // We were already at the beginning, no possible path found
+                    logger.info("Found no possible path out of [" + start + "] to [" + dest + "].");
+                    return null;  // Found no possible path from start to dest
                 }
             }