add comments to processor package

src/processor/Action.java

@@ -9,10 +9,28 @@ package processor;
  *
  */
 public enum Action {
+    /**
+     *  step into in forwards direction
+     */
     FORWARD,
+    /**
+     *  step over in forwards direction
+     */
     FORWARD_OVER,
+    /**
+     *  step out in forwards direction
+     */
     FORWARD_OUT,
+    /**
+     *  step into in backwards direction
+     */
     BACKWARD,
+    /**
+     *  step over in backwards direction
+     */
     BACKWARD_OVER,
+    /**
+     *  step out in backwards direction
+     */
     BACKWARD_OUT
 }

src/processor/ControlFlow.java

@@ -35,8 +35,8 @@ public class ControlFlow {
      */
     public ControlFlow( PseudoCodeNode functionNode )
     {
-    	status = CALL;
-    	function = functionNode;
+        status = CALL;
+        function = functionNode;
         jumpBack = null;
         reverse = null;
     }
@@ -69,7 +69,7 @@ public class ControlFlow {
     
     PseudoCodeNode getFunction()
     {
-    	return function;
+        return function;
     }
     
     int getStatus()

src/processor/Memory.java

@@ -92,12 +92,14 @@ public class Memory {
         switch( visibility )
         {
         case GLOBAL:
+            // declare the variable in the global memory
             this.global.declare( name, value );
             break;
         case COMPLETE_STACK:
         case LOCAL:
-        	if( stack.size() == 0 )
-        		return;
+            if( stack.size() == 0 )
+                return;
+            // declare the variable in the topmost stack frame
             stack.peek().declare( name, value );
             break;
         default:
@@ -119,23 +121,26 @@ public class Memory {
         switch( visibility )
         {
         case GLOBAL:
+            // set the variable in the global memory
             this.global.set( name, value );
             break;
         case COMPLETE_STACK:
         case LOCAL:
-        	int index = stack.size() - 1;
-        	while( index >= 0 ) {
-        	   StackFrame stackF = stack.get( index-- );
-        	   if( stackF.isDefined( name ) )
-        	   {
-        		   stackF.set( name, value );
-        		   return;
-        	   }
-        	   if( stackF.getType() == FrameType.FUNCTION )
-        		   break;
-        	}
-        	break;
+            // search the stack of the current function for this variable
+            int index = stack.size() - 1;
+            while( index >= 0 ) {
+               StackFrame stackF = stack.get( index-- );
+               if( stackF.isDefined( name ) )
+               {
+                   stackF.set( name, value );
+                   return;
+               }
+               if( stackF.getType() == FrameType.FUNCTION )
+                   break;
+            }
+            break;
         default:
+            // should never happen
             assert false;
             break;
         }
@@ -154,8 +159,10 @@ public class Memory {
         switch( visibility )
         {
         case GLOBAL:
+            // read from global memory
             return this.global.get( name );
         case LOCAL:
+            // search the stack of this function
             while( index >= 0 ) {
                 StackFrame stackF = stack.get( index-- );
                 if( stackF.isDefined( name ) )
@@ -165,6 +172,7 @@ public class Memory {
              }
             break;
         case COMPLETE_STACK:
+            // search the complete stack
             while( index >= 0 ) {
                 StackFrame stackF = stack.get( index-- );
                 if( stackF.isDefined( name ) )
@@ -172,6 +180,7 @@ public class Memory {
              }
             break;
         default:
+            // should never happen
             assert false;
             break;
         }
@@ -191,8 +200,10 @@ public class Memory {
         switch( visibility )
         {
         case GLOBAL:
+            // search in global memory
             return this.global.isDefined( name );
         case LOCAL:
+            // search in the stack of the current function
             while( index >= 0 ) {
                 StackFrame stackF = stack.get( index-- );
                 if( stackF.isDefined( name ) )
@@ -202,6 +213,7 @@ public class Memory {
              }
             break;
         case COMPLETE_STACK:
+          // search the whole stack
             while( index >= 0 ) {
                 StackFrame stackF = stack.get( index-- );
                 if( stackF.isDefined( name ) )
@@ -209,9 +221,11 @@ public class Memory {
              }
             break;
         default:
+            // should never happen
+            assert false;
             break;
         }
-    	return false;
+        return false;
     }
     
     /**
@@ -226,16 +240,20 @@ public class Memory {
         switch( visibility )
         {
         case GLOBAL:
+            // search in global memory
             return this.global.isDefined( name );
         case COMPLETE_STACK:
         case LOCAL:
+            // search the stack
             if( stack.size() == 0 )
                 return false;
             return stack.peek().isDefined( name );
         default:
+            // should never happen
+            assert false;
             break;
         }
-    	return false;
+        return false;
     }
     
     
@@ -249,15 +267,19 @@ public class Memory {
         switch( visibility )
         {
         case GLOBAL:
+            // undeclare global variable
             this.global.undeclare( name );
             break;
         case COMPLETE_STACK:
         case LOCAL:
-        	if( stack.size() == 0 )
-        		return;
+            // undeclare local variable in topmost frame
+            if( stack.size() == 0 )
+                return;
             stack.peek().undeclare( name );
             break;
         default:
+            // should never happen
+            assert false;
             break;
         }
     }

src/processor/ProcessController.java

@@ -42,12 +42,14 @@ public class ProcessController {
     {
         long old = lastTime;
         Action ret = null;
+        // wait until we know which action to do next
         synchronized( this ) {
             while( next == null )
                 wait();
             lastTime = System.currentTimeMillis();
             ret = next;
         }
+        // if we are in automatic execution mode, wait some time
         if( !continuous )
             next = null;
         else

src/processor/PseudoCodeNode.java

@@ -51,7 +51,7 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
         super( TextLayoutHelper.setupPseudoCode( description, vars ) );
         synchronized( PseudoCodeNode.class )
         {
-        	nodeId = nextNodeId++;
+            nodeId = nextNodeId++;
         }
         selected = false;
         this.tree = tree;
@@ -70,6 +70,7 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
      */
     public void setController( ProcessController c )
     {
+        // set the controller of all children
         if( children != null )
         {
             for( Object ch : children )
@@ -77,6 +78,7 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
                 ((PseudoCodeNode)ch).setController( c );
             }
         }
+        // set own controller
         controller = c;
     }
     
@@ -105,27 +107,10 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
         return selected;
     }
     
-    /**
-     * checks if one of the subnodes of this node is selected.
-     * @return true if one is, false otherwise
-     */
-    public boolean hasSelectedSubnode()
-    {
-    	if( children != null )
-    	{
-	    	for( Object ch : children )
-	        {
-	            if( ((PseudoCodeNode)ch).isSelected() || ((PseudoCodeNode)ch).hasSelectedSubnode() )
-	            	return true;
-	        }
-    	}
-    	return false;
-    }
-    
     private void expandToRoot()
     {
-    	if( parent != null )
-    		((PseudoCodeNode)parent).expandToRoot();
+        if( parent != null )
+            ((PseudoCodeNode)parent).expandToRoot();
         tree.expandPath( new TreePath( this.getPath() ) );
     }
 
@@ -137,13 +122,16 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
      */
     public CodeAction setSelected( boolean selected )
     {
+        // breakpoint reached? then stop
         if( selected && breakPoint )
             controller.setContinuous( false );
+        
         this.selected = selected;
-        if( selected )
-        {
+        if( selected ) 
+        { // node has just been selected
             if( tree != null ) {
                 TreePath path = new TreePath( getPath() );
+                // check where the line is
                 Rectangle bounds = tree.getPathBounds(path);
                 if( bounds!= null )
                 {
@@ -152,6 +140,7 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
                     SwingUtilities.invokeLater( new Runnable() {
                         @Override
                         public void run() {
+                            // scroll to the code line
                             tree.scrollRectToVisible(bounds);
                         }
                     });
@@ -162,13 +151,14 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
                 SwingUtilities.invokeLater( new Runnable() {
                     @Override
                     public void run() {
+                        // expand everything up to this line
                         expandToRoot();
                     }
                 });
             }
         }
         else
-        {
+        { // selection was removed
             if( controller != null && controller.getAutoCollapseOption() == 1 )
             {
                 SwingUtilities.invokeLater( new Runnable() {
@@ -222,6 +212,7 @@ public class PseudoCodeNode extends DefaultMutableTreeNode {
      */
     public ControlFlow emptyForwardStep( Memory m )
     {
+        // add an action to undo the step (empty backwards action)
         code.createEmptyBackwardsAction();
         ControlFlow cf = new ControlFlow( ControlFlow.STEP_OVER );
         cf.setJumpBack( this );

src/processor/PseudoCodeProcessor.java

@@ -42,7 +42,7 @@ public class PseudoCodeProcessor extends Thread {
     private boolean renderImage = true;
     private JFrame view;
     private ProcessController controller;
-    private boolean insideNotSkipLoop = false; // needet to avoid stack overflow errors
+    private boolean insideNotSkipLoop = false; // needed to avoid stack overflow errors
     
     /**
      * creates a new {@link PseudoCodeProcessor}
@@ -65,30 +65,57 @@ public class PseudoCodeProcessor extends Thread {
     
     public ProcessController getController()
     {
-    	return controller;
+        return controller;
     }
     
     private CodeStatus selectNextNode( PseudoCodeNode next, PseudoCodeNode last )
     {
         programPointer = next;
         last.setSelected( false );
-        switch( next.setSelected( true ) )
-        {
+        switch( next.setSelected( true ) ) // check which node should be executed next
+        { 
         case CONTINUE:
+            // just do the next step
             skip = false;
             return CodeStatus.UNFINISHED;
         case SKIP:
+            // node is folded so it is skipped
             skip = true;
             if( insideNotSkipLoop )
                 return CodeStatus.UNFINISHED;
             return forwardStepOverUntilNotSkip();
         case STOP:
+            // a breakpoint was reached
             skip = false;
             return CodeStatus.BREAKPOINT;
         default:
-            break;
+            return CodeStatus.UNFINISHED;
+        }
+    }
+    
+    private CodeStatus selectBeforeNode( PseudoCodeNode next, PseudoCodeNode last )
+    {
+        programPointer = next;
+        last.setSelected( false );
+        switch( next.setSelected( true ) ) // check which node should be executed next
+        {
+        case CONTINUE:
+            // just do the previous step
+            skip = false;
+            return CodeStatus.UNFINISHED;
+        case SKIP:
+            // node is folded so it is skipped
+            skip = true;
+            if( insideNotSkipLoop )
+                return CodeStatus.UNFINISHED;
+            return backwardStepOverUntilNotSkip();
+        case STOP:
+            // a breakpoint was reached
+            skip = false;
+            return CodeStatus.BREAKPOINT;
+        default:
+            return CodeStatus.UNFINISHED;
         }
-        return CodeStatus.UNFINISHED;
     }
     
     /**
@@ -97,11 +124,16 @@ public class PseudoCodeProcessor extends Thread {
      */
     protected CodeStatus forwardStep()
     {
+        // is the program pointer still available?
         if( programPointer == null )
             return CodeStatus.FINISHED;
+        
+        // read topmost stack frame
         StackFrame before = mem.removeFrame();
         mem.addFrame( before );
         ControlFlow cf = null;
+        
+        // remember if this node has already been called
         if( mem.isDefined( "_call" + programPointer.getId(), Visibility.LOCAL ) )
         {
             String name = "_call" + programPointer.getId();
@@ -113,11 +145,16 @@ public class PseudoCodeProcessor extends Thread {
         }
         else
             cf = programPointer.forwardStep( mem );
+        // remember all ControlFlow actions that have been done to be able to undo it later
         controlStack.push( cf );
+        
+        // get the debug output
         currentDebugOutput = programPointer.getDebugOutput( mem );
+        
         switch( cf.getStatus() )
-        {
+        { // we are doing a "step into"
         case ControlFlow.STEP_INTO:
+            // remember current line to be able to jump back to
             if( mem.isDefined( "_returnTo" + programPointer.getId(), Visibility.GLOBAL ) )
             {
                 String name = "_returnTo" + programPointer.getId();
@@ -132,9 +169,10 @@ public class PseudoCodeProcessor extends Thread {
                 throw new IllegalStateException( "A Codeline without sublines tried to make a STEP_INTO." );
             else
                 return selectNextNode( (PseudoCodeNode)programPointer.getFirstChild(), programPointer );
-        case ControlFlow.STEP_OVER:
+        case ControlFlow.STEP_OVER: // we are doing a "step over"
             if( programPointer.getParent() == null )
                 return CodeStatus.FINISHED;
+            // remember current line to be able to jump back to
             if( before.isDefined( "_returnTo" + programPointer.getId() ) )
             {
                 String name = "_returnTo" + programPointer.getId();
@@ -143,15 +181,18 @@ public class PseudoCodeProcessor extends Thread {
                 cf.setBackwardAction( (Memory m) -> {
                     before.declare( name, nextPC );
                 });
+                // continue with next node
                 return selectNextNode( nextPC, programPointer );
             }
+            // update program pointer
             PseudoCodeNode nextPC = (PseudoCodeNode) ((PseudoCodeNode)programPointer.getParent()).getChildAfter( programPointer );
             if( nextPC == null )
                 return selectNextNode( (PseudoCodeNode)programPointer.getParent(), programPointer );
             else
                 return selectNextNode( nextPC, programPointer );
-        case ControlFlow.CALL:
+        case ControlFlow.CALL: // we are doing a function call
             PseudoCodeNode f = cf.getFunction();
+            // remember current line to be able to jump back to
             String name = "_call" + programPointer.getId();
             mem.declare( name, true, Visibility.LOCAL );
             mem.declare( "_returnTo" + f.getId(), cf.getJumpBack(), Visibility.GLOBAL );
@@ -159,17 +200,19 @@ public class PseudoCodeProcessor extends Thread {
                 m.undeclare( "_returnTo" + f.getId(), Visibility.GLOBAL );
                 m.undeclare( name, Visibility.LOCAL );
             });
+            // go to next node
             return selectNextNode( f, programPointer );
         default:
-            break;
+            throw new IllegalStateException( "Unknown ControlFlow action" );
         }
-        throw new IllegalStateException( "Unknown ControlFlow action" );
     }
     
     private CodeStatus forwardStepOverUntilNotSkip() {
+        // is the program pointer still available?
         if( programPointer == null )
             return CodeStatus.FINISHED;
         CodeStatus status = CodeStatus.UNFINISHED;
+        // perform steps until someone sets skip to false
         do {
             insideNotSkipLoop = true;
             status = forwardStep();
@@ -180,10 +223,13 @@ public class PseudoCodeProcessor extends Thread {
     
     protected CodeStatus forwardStepOver()
     {
+        // is the program pointer still available?
         if( programPointer == null )
             return CodeStatus.FINISHED;
+        // remember stack size
         int stackSize = mem.getSize();
         CodeStatus status = CodeStatus.UNFINISHED;
+        // perform steps until we arrive at the same stack size again
         do {
             status = forwardStep();
         } while( mem.getSize() > stackSize && status == CodeStatus.UNFINISHED );
@@ -192,39 +238,23 @@ public class PseudoCodeProcessor extends Thread {
     
     protected CodeStatus forwardStepOut()
     {
+        // is the program pointer still available?
         if( programPointer == null )
             return CodeStatus.FINISHED;
+        // remember stack size
         int stackSize = mem.getSize();
         CodeStatus status = CodeStatus.UNFINISHED;
+        // perform steps until we arrive at a smaller stack size
         do {
             status = forwardStep();
         } while( mem.getSize() >= stackSize && status == CodeStatus.UNFINISHED );
         return status;
     }
     
-    private CodeStatus selectBeforeNode( PseudoCodeNode next, PseudoCodeNode last )
-    {
-        programPointer = next;
-        last.setSelected( false );
-        switch( next.setSelected( true ) )
-        {
-        case CONTINUE:
-            skip = false;
-            return CodeStatus.UNFINISHED;
-        case SKIP:
-            skip = true;
-            if( insideNotSkipLoop )
-                return CodeStatus.UNFINISHED;
-            return backwardStepOverUntilNotSkip();
-        case STOP:
-            skip = false;
-            return CodeStatus.BREAKPOINT;
-        default:
-            break;
-        }
-        return CodeStatus.UNFINISHED;
-    }
-    
+    /**
+     * returns the program pointer of the previous step
+     * @return the node that was previously executed
+     */
     protected PseudoCodeNode getLastProgramPointer() {
         if( controlStack.isEmpty() )
             return null;
@@ -233,21 +263,28 @@ public class PseudoCodeProcessor extends Thread {
     
     protected CodeStatus backwardStep()
     {
+        // check if we arrived at the beginning
         if( controlStack.isEmpty() )
             return CodeStatus.FINISHED;
+        // what did we do before?
         ControlFlow cf = controlStack.pop();
+        // where where we before?
         PseudoCodeNode nextPC = cf.getJumpBack();
+        // undo action
         cf.backward( mem );
         nextPC.backwardStep( mem );
+        
         currentDebugOutput = nextPC.getDebugOutput( mem );
         return selectBeforeNode( nextPC, programPointer );
     }
     
     private CodeStatus backwardStepOverUntilNotSkip()
     {
+        // check if we arrived at the beginning
         if( programPointer == null )
             return CodeStatus.FINISHED;
         CodeStatus status = CodeStatus.UNFINISHED;
+        // perform steps until someone sets skip to false
         do {
             insideNotSkipLoop = true;
             status = backwardStep();
@@ -258,10 +295,13 @@ public class PseudoCodeProcessor extends Thread {
     
     protected CodeStatus backwardStepOver()
     {
+        // check if we arrived at the beginning
         if( programPointer == null )
             return CodeStatus.FINISHED;
+        
         int stackSize = mem.getSize();
         CodeStatus status = CodeStatus.UNFINISHED;
+        // perform steps until we arrrive at the same stack size again
         do {
             status = backwardStep();
         } while( mem.getSize() > stackSize && status == CodeStatus.UNFINISHED );
@@ -270,10 +310,13 @@ public class PseudoCodeProcessor extends Thread {
     
     protected CodeStatus backwardStepOut()
     {
+        // check if we arrived at the beginning
         if( programPointer == null )
             return CodeStatus.FINISHED;
+        
         int stackSize = mem.getSize();
         CodeStatus status = CodeStatus.UNFINISHED;
+        // perform steps until we arrrive at a smaller stack size
         do {
             status = backwardStep();
         } while( mem.getSize() >= stackSize && status == CodeStatus.UNFINISHED );
@@ -305,14 +348,14 @@ public class PseudoCodeProcessor extends Thread {
     {
         while( true ) // if this loop would end we could not undo steps any more
         {
-        	CodeStatus status = null;
+            CodeStatus status = null;
             try {
-                Action action = controller.getNextAction();
-                graph.unselectGraph();
-                switch( action )
+                Action action = controller.getNextAction(); // what action is next?
+                graph.unselectGraph(); // remove selection from any nodes in the graph
+                switch( action ) // perform the action
                 {
                 case FORWARD:
-                	status = forwardStep();
+                    status = forwardStep();
                     break;
                 case FORWARD_OUT:
                     status = forwardStepOut();
@@ -341,11 +384,14 @@ public class PseudoCodeProcessor extends Thread {
                 e.printStackTrace();
                 return;
             }
-            update();
-            if( status == CodeStatus.FINISHED )
+            
+            // update the drawing
+            update(); 
+            
+            if( status == CodeStatus.FINISHED ) // stop at the end
             {
-            	controller.setContinuous( false );
-            	controller.setNextAction( null );
+                controller.setContinuous( false );
+                controller.setNextAction( null );
             }
         }
     }

src/processor/StackFrame.java

@@ -15,23 +15,23 @@ public class StackFrame {
      * @author kolja
      *
      */
-	public enum FrameType {
-		FUNCTION,
-		LOOP
-	}
-	
+    public enum FrameType {
+        FUNCTION,
+        LOOP
+    }
+
     private HashMap< String, Object > data;
     private FrameType type;
     
     public StackFrame( FrameType type )
     {
-    	this.type = type;
+        this.type = type;
         data = new HashMap< String, Object >();
     }
     
     public FrameType getType()
     {
-    	return type;
+        return type;
     }
     
     /**

src/view/PseudoCodeLines.java

@@ -128,7 +128,7 @@ public class PseudoCodeLines extends JComponent implements MouseListener{
             Rectangle rect = tree.getRowBounds( i );
             String text = String.valueOf( number );
             int yPosition = rect.y + rect.height / 2 + 4;
-            if( !node.hasSelectedSubnode() && node.isSelected() )
+            if( node.isSelected() )
                 g.drawImage( currentLine.getImage(), HORIZONTAL_PADDING, rect.y + rect.height / 2 - 10, 20, 20, null );
             g2d.drawString( text, HORIZONTAL_PADDING * 2 + 20, yPosition );
             if( node.hasBreakPoint() )