Index: trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/nodeequality/IterationComparisonRule.java
===================================================================
--- trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/nodeequality/IterationComparisonRule.java	(revision 439)
+++ trunk/quest-core-tasktrees/src/main/java/de/ugoe/cs/quest/tasktrees/nodeequality/IterationComparisonRule.java	(revision 557)
@@ -1,3 +1,2 @@
-//-------------------------------------------------------------------------------------------------
 // Module    : $RCSfile: NodeIdentityRule.java,v $
 // Version   : $Revision: 0.0 $  $Author: patrick $  $Date: 19.02.2012 $
@@ -5,129 +4,165 @@
 // Creation  : 2012 by patrick
 // Copyright : Patrick Harms, 2012
-//-------------------------------------------------------------------------------------------------
+
 package de.ugoe.cs.quest.tasktrees.nodeequality;
 
-import de.ugoe.cs.quest.tasktrees.treeifc.Iteration;
-import de.ugoe.cs.quest.tasktrees.treeifc.Selection;
-import de.ugoe.cs.quest.tasktrees.treeifc.TaskTreeNode;
+import de.ugoe.cs.quest.tasktrees.treeifc.IIteration;
+import de.ugoe.cs.quest.tasktrees.treeifc.ISelection;
+import de.ugoe.cs.quest.tasktrees.treeifc.ITaskTreeNode;
 
-//-------------------------------------------------------------------------------------------------
 /**
- * TODO comment
+ * <p>
+ * This class is capable of comparing Iterations. Iterations equal at distinct levels
+ * in distinct situations. The following table shows the results of the comparison for the
+ * specific situations (the parameters are commutative). In any other situation, the comparison
+ * returns <code>NodeEquality.UNEQUAL</code>:
+ * </p>
+ * 
+ * <table border="1">
+ *   <tr>
+ *     <th>iteration 1</th>
+ *     <th>iteration 2</th>
+ *     <th>comparison result</th>
+ *   </tr>
+ *   <tr>
+ *     <td>any iteration</td>
+ *     <td>any iteration with a child that is lexically equal to the child of iteration 1</td>
+ *     <td><code>NodeEquality.LEXICALLY_EQUAL</code></td>
+ *   </tr>
+ *   <tr>
+ *     <td>any iteration</td>
+ *     <td>any iteration with a child that is syntactically equal to the child of iteration 1</td>
+ *     <td><code>NodeEquality.SYNTACTICALLY_EQUAL</code></td>
+ *   </tr>
+ *   <tr>
+ *     <td>any iteration</td>
+ *     <td>any iteration with a child that is semantically equal to the child of iteration 1</td>
+ *     <td><code>NodeEquality.SEMANTICALLY_EQUAL</code></td>
+ *   </tr>
+ *   <tr>
+ *     <td>an iteration with a selection of syntactically equal children</td>
+ *     <td>an iteration with a child that is syntactically equal to the children of the child
+ *     selection of iteration 1</td>
+ *     <td><code>NodeEquality.SYNTACTICALLY_EQUAL</code></td>
+ *   </tr>
+ *   <tr>
+ *     <td>an iteration with a selection of semantically equal children</td>
+ *     <td>an iteration with a child that is semantically equal to the children of the child
+ *     selection of iteration 1</td>
+ *     <td><code>NodeEquality.SEMANTICALLY_EQUAL</code></td>
+ *   </tr>
+ * </table>
  * 
  * @version $Revision: $ $Date: 19.02.2012$
  * @author 2012, last modified by $Author: patrick$
  */
-//-------------------------------------------------------------------------------------------------
-public class IterationComparisonRule implements NodeComparisonRule
-{
-  /** */
-  private NodeEqualityRuleManager mRuleManager;
+public class IterationComparisonRule implements NodeComparisonRule {
+    
+    /** the rule manager for internally comparing task tree nodes */
+    private NodeEqualityRuleManager mRuleManager;
 
-  //-----------------------------------------------------------------------------------------------
-  /**
-   * TODO: comment
-   *
-   */
-  //-----------------------------------------------------------------------------------------------
-  IterationComparisonRule(NodeEqualityRuleManager ruleManager)
-  {
-    super();
-    mRuleManager = ruleManager;
-  }
-
-  //-----------------------------------------------------------------------------------------------
-  /* (non-Javadoc)
-   * @see de.ugoe.cs.tasktree.nodeequality.NodeEqualityRule#apply(TaskTreeNode, TaskTreeNode)
-   */
-  //-----------------------------------------------------------------------------------------------
-  @Override
-  public NodeEquality compare(TaskTreeNode node1, TaskTreeNode node2)
-  {
-    if ((!(node1 instanceof Iteration)) || (!(node2 instanceof Iteration)))
-    {
-      return null;
-    }
-    
-    // if both iterations do not have children, they are equal although this doesn't make sense
-    if ((node1.getChildren().size() == 0) && (node2.getChildren().size() == 0))
-    {
-      return new NodesIdentical();
-    }
-    
-    TaskTreeNode child1 = node1.getChildren().get(0);
-    TaskTreeNode child2 = node2.getChildren().get(0);
-    
-    // iterations may have 3 different structures.
-    //   1. they have one child, which is the iterated one
-    //   2. they have a sequence of children, which is iterated
-    //   3. they have a selection of different iterated variants (usually the variants are
-    //      semantically equal)
-    //
-    // the permutations of the three variants in combination must be checked
-    
-    // check if both nodes are the same variants of iterations and if their children are equal.
-    // This condition matches, if both iterations are the same variants of iteration. I.e. three
-    // combinations of the permutation are handled herewith.
-    NodeEquality nodeEquality = mRuleManager.applyRules(child1, child2);
-      
-    if (nodeEquality.getStructuralEquality() || nodeEquality.getSemanticalEquality())
-    {
-      return nodeEquality;
-    }
-    
-    // compare one iteration with a single node as a child and another one with a selection of
-    // semantically equal nodes
-    if (selectionChildrenSemanticallyEqualNode(child1, child2))
-    {
-      return new NodesSemanticallyEqual();
+    /**
+     * <p>
+     * simple constructor to provide the rule with the node equality rule manager to be able
+     * to perform comparisons of the children of provided task tree nodes
+     * </p>
+     * 
+     * @param ruleManager the rule manager for comparing task tree nodes
+     */
+    IterationComparisonRule(NodeEqualityRuleManager ruleManager) {
+        super();
+        mRuleManager = ruleManager;
     }
 
-    // all other combinations (i.e. sequence with single child and sequence with selection)
-    // can not match
-    return null;
-  }
+    /*
+     * (non-Javadoc)
+     * 
+     * @see de.ugoe.cs.tasktree.nodeequality.NodeEqualityRule#apply(TaskTreeNode, TaskTreeNode)
+     */
+    @Override
+    public NodeEquality compare(ITaskTreeNode node1, ITaskTreeNode node2) {
+        if ((!(node1 instanceof IIteration)) || (!(node2 instanceof IIteration))) {
+            return null;
+        }
 
-  //-----------------------------------------------------------------------------------------------
-  /**
-   * TODO: comment
-   *
-   * @param taskTreeNode
-   * @param taskTreeNode2
-   * @return
-   */
-  //-----------------------------------------------------------------------------------------------
-  private boolean selectionChildrenSemanticallyEqualNode(TaskTreeNode taskTreeNode,
-                                                         TaskTreeNode taskTreeNode2)
-  {
-    Selection selection = null;
-    TaskTreeNode node = null;
-    if (taskTreeNode instanceof Selection)
+        // if both iterations do not have children, they are equal although this doesn't make sense
+        if ((node1.getChildren().size() == 0) && (node2.getChildren().size() == 0)) {
+            return NodeEquality.IDENTICAL;
+        }
+
+        ITaskTreeNode child1 = node1.getChildren().get(0);
+        ITaskTreeNode child2 = node2.getChildren().get(0);
+
+        // iterations may have 3 different structures.
+        // 1. they have one child, which is the iterated one
+        // 2. they have a sequence of children, which is iterated
+        // 3. they have a selection of different iterated variants (usually the variants are
+        // semantically equal)
+        //
+        // the permutations of the three variants in combination must be checked
+
+        // check if both nodes are the same variants of iterations and if their children are equal.
+        // This condition matches, if both iterations are the same variants of iteration. I.e. three
+        // combinations of the permutation are handled herewith.
+        NodeEquality nodeEquality = mRuleManager.applyRules(child1, child2);
+
+        if (nodeEquality.isAtLeast(NodeEquality.SEMANTICALLY_EQUAL)) {
+            return nodeEquality;
+        }
+
+        // compare one iteration with a single node as a child and another one with a selection of
+        // semantically equal nodes
+        return selectionChildrenSemanticallyEqualNode(child1, child2);
+        
+        // all other combinations (i.e. sequence with single child and sequence with selection)
+        // can not match
+    }
+
+    /**
+     * <p>
+     * compares two task tree nodes. One of them must be a selection of at least semantically
+     * equal children. The other one can be any task tree node. The method returns a node equality
+     * that is not <code>NodeEquality.UNEQUAL</code> if the other node is at least semantically
+     * equal to the children of the selection. It returns more concrete equalities, if the
+     * equality between the other node and the children of the selection is more concrete.
+     * </p> 
+     * 
+     * @param taskTreeNode  the first task tree node to compare
+     * @param taskTreeNode2 the second task tree node to compare
+     * 
+     * @return as described
+     */
+    private NodeEquality selectionChildrenSemanticallyEqualNode(ITaskTreeNode taskTreeNode,
+                                                                ITaskTreeNode taskTreeNode2)
     {
-      selection = (Selection) taskTreeNode;
-      node = taskTreeNode2;
+        ISelection selection = null;
+        ITaskTreeNode node = null;
+        if (taskTreeNode instanceof ISelection) {
+            selection = (ISelection) taskTreeNode;
+            node = taskTreeNode2;
+        }
+        else if (taskTreeNode2 instanceof ISelection) {
+            selection = (ISelection) taskTreeNode2;
+            node = taskTreeNode;
+        }
+        else {
+            return NodeEquality.UNEQUAL;
+        }
+
+        NodeEquality lessConcreteEqualityForAllComparisons = NodeEquality.IDENTICAL;
+
+        for (ITaskTreeNode child : selection.getChildren()) {
+            NodeEquality nodeEquality = mRuleManager.applyRules(node, child);
+
+            if (!nodeEquality.isAtLeast(NodeEquality.SEMANTICALLY_EQUAL)) {
+                return NodeEquality.UNEQUAL;
+            }
+            else if (!lessConcreteEqualityForAllComparisons.isAtLeast(nodeEquality)) {
+                lessConcreteEqualityForAllComparisons = nodeEquality;
+            }
+        }
+
+        return lessConcreteEqualityForAllComparisons;
     }
-    else if (taskTreeNode2 instanceof Selection)
-    {
-      selection = (Selection) taskTreeNode2;
-      node = taskTreeNode;
-    }
-    else
-    {
-      return false;
-    }
-    
-    for (TaskTreeNode child : selection.getChildren())
-    {
-      NodeEquality nodeEquality = mRuleManager.applyRules(node, child);
-          
-      if (!nodeEquality.getStructuralEquality() && !nodeEquality.getSemanticalEquality())
-      {
-        return false;
-      }
-    }
-    
-    return true;
-  }
 
 }
