Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/GUIEventTaskComparisonRule.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/GUIEventTaskComparisonRule.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/GUIEventTaskComparisonRule.java	(revision 1154)
@@ -133,10 +133,17 @@
      * returns lexical equality.
      * </p>
-     *
-     * @param interaction1 the first interaction to compare
-     * @param interaction2 the second interaction to compare
-     * @param eventTarget  the event target on which the interactions happened (used within
-     *                     special comparisons like mouse clicks on buttons, where the coordinates
-     *                     can be ignored)
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level can be at most as
+     * concrete as the provided one. If the provided one is null, it is expected to be lexical
+     * equality.
+     * </p>
+     *
+     * @param interaction1  the first interaction to compare
+     * @param interaction2  the second interaction to compare
+     * @param eventTarget   the event target on which the interactions happened (used within
+     *                      special comparisons like mouse clicks on buttons, where the coordinates
+     *                      can be ignored)
+     * @param equalityLevel the equality level to be checked for
      * 
      * @return as described
@@ -192,12 +199,20 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param interaction1
-     * @param interaction2
-     * @param eventTarget
-     * @param level
-     * @return
+     * compares two key interactions. If both are of the same type and if both have the
+     * same key, they are lexically equal. If both are only of the same type, they are
+     * semantically equal. Otherwise, they are unequal.
+     * </p>
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level is as concrete as
+     * the provided one. It may be more concrete if there is no difference regarding the
+     * comparison on the levels.
+     * </p>
+     *
+     * @param interaction1  the first key interaction
+     * @param interaction2  the second key interaction
+     * @param equalityLevel the equality level to be checked for
+     * 
+     * @return as described
      */
     private TaskEquality compareKeyInteractions(KeyInteraction interaction1,
@@ -227,7 +242,14 @@
      * coordinates, they are lexically equal. Otherwise, they are semantically equal.
      * </p>
-     *
-     * @param interaction1 the first mouse drag and drop to compare
-     * @param interaction2 the second mouse drag and drop to compare
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level is as concrete as
+     * the provided one. It may be more concrete if there is no difference regarding the
+     * comparison on the levels.
+     * </p>
+     *
+     * @param interaction1  the first mouse drag and drop to compare
+     * @param interaction2  the second mouse drag and drop to compare
+     * @param equalityLevel the equality level to be checked for
      * 
      * @return as described
@@ -267,10 +289,17 @@
      * lexically equal.
      * </p>
-     *
-     * @param interaction1 the first mouse button interaction to compare
-     * @param interaction2 the second mouse button interaction to compare
-     * @param eventTarget  the event target on which the interactions happened (used within
-     *                     special comparisons like mouse clicks on buttons, where the coordinates
-     *                     can be ignored)
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level is as concrete as
+     * the provided one. It may be more concrete if there is no difference regarding the
+     * comparison on the levels.
+     * </p>
+     *
+     * @param interaction1  the first mouse button interaction to compare
+     * @param interaction2  the second mouse button interaction to compare
+     * @param eventTarget   the event target on which the interactions happened (used within
+     *                      special comparisons like mouse clicks on buttons, where the coordinates
+     *                      can be ignored)
+     * @param equalityLevel the equality level to be checked for
      * 
      * @return as described
@@ -334,10 +363,17 @@
      * lexically equal.
      * </p>
-     *
-     * @param interaction1 the first mouse button interaction to compare
-     * @param interaction2 the second mouse button interaction to compare
-     * @param eventTarget  the event target on which the interactions happened (used within
-     *                     special comparisons like mouse clicks on buttons, where the coordinates
-     *                     can be ignored)
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level is as concrete as
+     * the provided one. It may be more concrete if there is no difference regarding the
+     * comparison on the levels.
+     * </p>
+     *
+     * @param interaction1  the first mouse button interaction to compare
+     * @param interaction2  the second mouse button interaction to compare
+     * @param eventTarget   the event target on which the interactions happened (used within
+     *                      special comparisons like mouse clicks on buttons, where the coordinates
+     *                      can be ignored)
+     * @param equalityLevel the equality level to be checked for
      * 
      * @return as described
@@ -368,7 +404,14 @@
      * (the equality of the event targets is checked beforehand).
      * </p>
-     *
-     * @param interaction1 the first text input to compare
-     * @param interaction2 the second text input to compare
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level is as concrete as
+     * the provided one. It may be more concrete if there is no difference regarding the
+     * comparison on the levels.
+     * </p>
+     *
+     * @param interaction1  the first text input to compare
+     * @param interaction2  the second text input to compare
+     * @param equalityLevel the equality level to be checked for
      * 
      * @return as described
@@ -402,7 +445,14 @@
      * (the equality of the event targets is checked beforehand).
      * </p>
-     *
-     * @param interaction1 the first value selection to compare
-     * @param interaction2 the second value selection to compare
+     * <p>
+     * The provided equality level can be used to restrict the quality check to the given level.
+     * This is done for optimization purposes. The returned equality level is as concrete as
+     * the provided one. It may be more concrete if there is no difference regarding the
+     * comparison on the levels.
+     * </p>
+     *
+     * @param interaction1  the first value selection to compare
+     * @param interaction2  the second value selection to compare
+     * @param equalityLevel the equality level to be checked for
      * 
      * @return as described
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/IterationComparisonRule.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/IterationComparisonRule.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/IterationComparisonRule.java	(revision 1154)
@@ -222,5 +222,15 @@
 
     /**
-     * TODO update comment
+     * <p>
+     * compares two tasks with each other by calling the rule manager. If the rule manager returns
+     * identity, then the returned equality is set to lexically equal. The reason is, that
+     * the children of the iterations are compared and that therefore the distinct iterations
+     * can be at most lexically equal.
+     * </p>
+     * 
+     * @param child1 the first task to be compared
+     * @param child2 the second task to be compared
+     * 
+     * @return the determined equality being at most lexical equality.
      */
     private TaskEquality getNodeEquality(ITask child1, ITask child2) {
@@ -243,6 +253,6 @@
     /**
      * <p>
-     * compares two tasks. One of them must be a selection, the other one can be any task
-     * tree task. The method returns a task equality that is not <code>NodeEquality.UNEQUAL</code>
+     * compares two tasks. One of them must be a selection, the other one can be any task.
+     * The method returns a task equality that is not <code>NodeEquality.UNEQUAL</code>
      * if the other task is at least semantically equal to the children of the selection. It
      * returns more concrete equalities, if the equality between the other task and the children
@@ -250,6 +260,6 @@
      * </p> 
      * 
-     * @param taskTreeNode  the first task to compare
-     * @param taskTreeNode2 the second task to compare
+     * @param task1 the first task to compare
+     * @param task2 the second task to compare
      * 
      * @return as described
@@ -292,11 +302,15 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @param requiredEqualityLevel
-     * @return
+     * used to to call the task equality rule manager for the comparison of the two provided
+     * children. If no required equality level is provided, than the most concrete equality is
+     * returned. Otherwise, the required equality is returned as long as the children are equal
+     * on that level.
+     * </p> 
+     * 
+     * @param child1                the first task to be compared
+     * @param child2                the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality
      */
     private TaskEquality callRuleManager(ITask        child1,
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/SelectionComparisonRule.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/SelectionComparisonRule.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/SelectionComparisonRule.java	(revision 1154)
@@ -29,5 +29,6 @@
  * equal, then the selections are syntactically equal. If all children are at least semantically
  * equal, then the selections are semantically equal. If only one of the selections has children,
- * then the selections are unequal.
+ * then the selections are unequal. The comparison is broken up, if only a specific equality is
+ * checked for and this equality is ensured.
  * </p>
  * 
@@ -97,5 +98,15 @@
 
     /**
-     * 
+     * <p>
+     * compares two selections with each other checking for the provided required level of
+     * equality. If this level is ensured, the method immediately returns. The more concrete
+     * the required equality level, the more checks this method performs.
+     * </p>
+     * 
+     * @param task1                 the first task to be compared
+     * @param task2                 the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality.
      */
     private TaskEquality getEquality(ITask task1, ITask task2, TaskEquality requiredEqualityLevel) {
@@ -141,10 +152,14 @@
     /**
      * <p>
-     * TODO: comment
+     * determines the common equality level for all tasks in the first list compared to all
+     * tasks in the second list. If for one task in the first list, there is no equal task in the
+     * second list, the method return unequality. 
      * </p>
      *
-     * @param children1
-     * @param children2
-     * @param requiredEqualityLevel
+     * @param children1 the first list to be compared
+     * @param children2 the second list to be compared
+     * 
+     * @return the common task equality identified for all tasks in the first list with respect to
+     *         the second list
      */
     private TaskEquality getCommonEqualityLevel(List<ITask> children1, List<ITask> children2) {
@@ -188,10 +203,14 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param children1
-     * @param children2
-     * @param requiredEqualityLevel
+     * ensures for the two given lists, that for each task in the first list there is a task
+     * in the second list being on the given level equal to the task in the first list.
+     * </p> 
+     * 
+     * @param children1             the first list to be compared
+     * @param children2             the second list to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return true if each task in the first list has an equal task in the second list when
+     *         considering the given equality level, false else.
      */
     private boolean checkEqualityLevel(List<ITask>  children1,
@@ -227,11 +246,15 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @param requiredEqualityLevel
-     * @return
+     * used to to call the task equality rule manager for the comparison of the two provided
+     * children. If no required equality level is provided, than the most concrete equality is
+     * returned. Otherwise, the required equality is returned as long as the children are equal
+     * on that level.
+     * </p> 
+     * 
+     * @param child1                the first task to be compared
+     * @param child2                the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality
      */
     private TaskEquality callRuleManager(ITask        child1,
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/SequenceComparisonRule.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/SequenceComparisonRule.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/SequenceComparisonRule.java	(revision 1154)
@@ -93,5 +93,15 @@
 
     /**
+     * <p>
+     * compares two sequences with each other checking for the provided required level of
+     * equality. If this level is ensured, the method immediately returns. The more concrete
+     * the required equality level, the more checks this method performs.
+     * </p>
      * 
+     * @param task1                 the first task to be compared
+     * @param task2                 the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality.
      */
     private TaskEquality getEquality(ITask task1, ITask task2, TaskEquality requiredEqualityLevel) {
@@ -127,11 +137,15 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @param requiredEqualityLevel
-     * @return
+     * used to to call the task equality rule manager for the comparison of the two provided
+     * children. If no required equality level is provided, than the most concrete equality is
+     * returned. Otherwise, the required equality is returned as long as the children are equal
+     * on that level.
+     * </p> 
+     * 
+     * @param child1                the first task to be compared
+     * @param child2                the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality
      */
     private TaskEquality callRuleManager(ITask        child1,
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskAndIterationComparisonRule.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskAndIterationComparisonRule.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskAndIterationComparisonRule.java	(revision 1154)
@@ -93,5 +93,16 @@
 
     /**
+     * <p>
+     * compares two tasks with each other checking for the provided required level of
+     * equality. One of the tasks must be an iteration, the other one not. If this is not the
+     * case, the method returns null. The returned equality level is at most lexical equality
+     * as the iteration can not be identical to something not being an iteration.
+     * </p>
      * 
+     * @param task1                 the first task to be compared
+     * @param task2                 the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality.
      */
     private TaskEquality getEquality(ITask task1, ITask task2, TaskEquality requiredEqualityLevel) {
@@ -144,11 +155,15 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @param requiredEqualityLevel
-     * @return
+     * used to to call the task equality rule manager for the comparison of the two provided
+     * children. If no required equality level is provided, than the most concrete equality is
+     * returned. Otherwise, the required equality is returned as long as the children are equal
+     * on that level.
+     * </p> 
+     * 
+     * @param child1                the first task to be compared
+     * @param child2                the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality
      */
     private TaskEquality callRuleManager(ITask        child1,
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskAndSelectionComparisonRule.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskAndSelectionComparisonRule.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskAndSelectionComparisonRule.java	(revision 1154)
@@ -94,5 +94,16 @@
     
     /**
-     * 
+     * <p>
+     * compares two tasks with each other checking for the provided required level of
+     * equality. One of the tasks must be a selection, the other one not. If this is not the
+     * case, the method returns null. The returned equality level is at most lexical equality
+     * as the selection can not be identical to something not being a selection.
+     * </p>
+     * 
+     * @param task1                 the first task to be compared
+     * @param task2                 the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality.
      */
     private TaskEquality getEquality(ITask task1, ITask task2, TaskEquality requiredEqualityLevel) {
@@ -168,11 +179,15 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @param requiredEqualityLevel
-     * @return
+     * used to to call the task equality rule manager for the comparison of the two provided
+     * children. If no required equality level is provided, than the most concrete equality is
+     * returned. Otherwise, the required equality is returned as long as the children are equal
+     * on that level.
+     * </p> 
+     * 
+     * @param child1                the first task to be compared
+     * @param child2                the second task to be compared
+     * @param requiredEqualityLevel the equality level to be checked for
+     * 
+     * @return the determined equality
      */
     private TaskEquality callRuleManager(ITask        child1,
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskComparator.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskComparator.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskComparator.java	(revision 1154)
@@ -24,6 +24,11 @@
 /**
  * <p>
- * TODO comment
+ * this class is a very fast implementation for the {@link SymbolComparator} interface to be
+ * applied on task instances. To be efficient, it caches information about the equality of tasks.
+ * Only, if it does not know a specific equality yet, it call the task equality rule manager
+ * to compare two tasks. Otherwise, it returns the known equality.
  * </p>
+ * 
+ * TODO improve documentation and remove stop watch stuff.
  * 
  * @author Patrick Harms
@@ -45,8 +50,16 @@
     private TaskEquality minimalNodeEquality;
 
-    /** */
+    /**
+     * <p>
+     * the internally used comparer for tasks.
+     * </p> 
+     */
     private Comparer comparer;
 
-    /** */
+    /**
+     * <p>
+     * the internally used comparer for tasks considering only lexical equality.
+     * </p> 
+     */
     private Comparer lexicalComparer;
 
Index: trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskEqualityRuleManager.java
===================================================================
--- trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskEqualityRuleManager.java	(revision 1146)
+++ trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/taskequality/TaskEqualityRuleManager.java	(revision 1154)
@@ -23,9 +23,7 @@
  * <p>
  * The task equality rule manager is capable of comparing tasks based on its internal list
- * of comparison rules. The current list of rules contains the {@link TaskIdentityRule}, the
- * {@link IterationComparisonRule}, the {@link SequenceComparisonRule}, and
- * {@link SelectionComparisonRule}. These rules are asked for comparing the two provided tasks
- * in the mentioned order. If a rule returns a task equality other than null, this equality is
- * returned. Otherwise the next rule is asked.
+ * of comparison rules. These rules are asked for comparing the two provided tasks. If a rule
+ * returns a task equality other than null, this equality is returned. Otherwise the next rule
+ * is asked.
  * </p>
  * 
@@ -35,5 +33,9 @@
 public class TaskEqualityRuleManager {
 
-    /** */
+    /**
+     * <p>
+     * the rules that can be used for comparing tasks
+     * </p>
+     */
     private List<TaskComparisonRule> mRuleIndex = null;
 
@@ -99,11 +101,16 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @param equalityLevel
-     * @return
+     * this method two tasks with respect to the fiven equality level and returns true, if this
+     * level is given.
+     * </p>
+     * 
+     * @param task1         the first task to be compared
+     * @param task2         the second task to be compared
+     * @param equalityLevel the level of equality to be checked for
+     * 
+     * @return as described
+     * 
+     * @throws IllegalStateException in the case, the {@link #init()} method was not called on the
+     *                               manager before a call to this method.
      */
     public boolean areAtLeastEqual(ITask task1, ITask task2, TaskEquality equalityLevel) {
@@ -130,10 +137,16 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @return
+     * this method checks if the two given tasks are identical. For this, it iterates its internal
+     * comparison rules. If the first rule returns true, than this method returns true as well.
+     * If no rule returns true, this method returns false.
+     * </p>
+     * 
+     * @param task1 the first task to be compared
+     * @param task2 the second task to be compared
+     * 
+     * @return as described
+     * 
+     * @throws IllegalStateException in the case, the {@link #init()} method was not called on the
+     *                               manager before a call to this method.
      */
     public boolean areIdentical(ITask task1, ITask task2) {
@@ -153,10 +166,16 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @return
+     * this method checks if the two given tasks are lexically equal. For this, it iterates its
+     * internal comparison rules. If the first rule returns true, than this method returns true
+     * as well. If no rule returns true, this method returns false.
+     * </p>
+     * 
+     * @param task1 the first task to be compared
+     * @param task2 the second task to be compared
+     * 
+     * @return as described
+     * 
+     * @throws IllegalStateException in the case, the {@link #init()} method was not called on the
+     *                               manager before a call to this method.
      */
     public boolean areLexicallyEqual(ITask task1, ITask task2) {
@@ -176,10 +195,16 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @return
+     * this method checks if the two given tasks are syntactically equal. For this, it iterates its
+     * internal comparison rules. If the first rule returns true, than this method returns true
+     * as well. If no rule returns true, this method returns false.
+     * </p>
+     * 
+     * @param task1 the first task to be compared
+     * @param task2 the second task to be compared
+     * 
+     * @return as described
+     * 
+     * @throws IllegalStateException in the case, the {@link #init()} method was not called on the
+     *                               manager before a call to this method.
      */
     public boolean areSyntacticallyEqual(ITask task1, ITask task2) {
@@ -199,10 +224,16 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param child1
-     * @param child2
-     * @return
+     * this method checks if the two given tasks are semantically equal. For this, it iterates its
+     * internal comparison rules. If the first rule returns true, than this method returns true
+     * as well. If no rule returns true, this method returns false.
+     * </p>
+     * 
+     * @param task1 the first task to be compared
+     * @param task2 the second task to be compared
+     * 
+     * @return as described
+     * 
+     * @throws IllegalStateException in the case, the {@link #init()} method was not called on the
+     *                               manager before a call to this method.
      */
     public boolean areSemanticallyEqual(ITask task1, ITask task2) {
