Changeset 1177 for trunk/autoquest-core-tasktrees

Timestamp:

04/25/13 16:59:20 (12 years ago)

Author:

pharms

Message:

• improved java doc

Location:

trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc

Files:

• ITaskInstance.java (modified) (1 diff)
• ITaskInstanceList.java (modified) (2 diffs)
• IUserSession.java (modified) (2 diffs)

trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskInstance.java

@@ -18 +18 @@
 
 /**
- * TODO comment
+ * <p>
+ * a task instance represents the execution of a specific task within a user session. A task
+ * instance is always related to the task that was executed. A task instance may have children
+ * but only if its related task allows to have children. For example, if the represented task is
+ * a sequence then task instance has children and these are instances of the tasks being the
+ * children of the related sequence.
+ * </p>
+ * <p>
+ * An instance of a sequence has the same number of children as the related sequence. An instance
+ * of a selection has only one child which is an instance of exactly one variant contained in the
+ * related selection. An instance of an iteration has zero or more instances of the same task
+ * as children where the task is the child of the related iteration. An instance of an optional
+ * has zero or one child where the task related to child is the child of the optional. A task
+ * instance related to an event task does not have children.
+ * </p>
  * 
- * @version $Revision: $ $Date: $
- * @author 2011, last modified by $Author: $
+ * @author Patrick Harms
  */
 public interface ITaskInstance extends ITaskInstanceList {
 
     /**
-     *
+     * <p>
+     * returns the children of the task instance if any. See class description for how many
+     * children can be expected. May return null.
+     * </p>
+     * 
+     * @return as described
      */
     public List<ITaskInstance> getChildren();
 
     /**
-     *
+     * <p>
+     * returns the task related to the instance.
+     * </p>
+     * 
+     * @return as described
      */
     public ITask getTask();
 
     /**
-     *
+     * <p>
+     * compares an instance to another one. Returns true if both instances are the same, i.e. not
+     * only the related task is equal but also all children and further characteristics of the
+     * task instance  
+     * </p>
+     * 
+     * @param taskInstance the instance to compare to
+     * 
+     * @return as described
      */
     public boolean equals(ITaskInstance taskInstance);
 
     /**
-     *
+     * <p>
+     * returns a hash code for the task instance to be able to put it into hash maps
+     * </p>
+     * 
+     * @return as described
      */
     public int hashCode();
 
     /**
-     *
+     * <p>
+     * clones a task instance by creating exact clones of each contained child instance as well
+     * as the related task. Furthermore, all other non transient information of the task
+     * instance must be cloned.
+     * </p>
+     * 
+     * @return a clone of the task instance
      */
     public ITaskInstance clone();

trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/ITaskInstanceList.java

@@ -19 +19 @@
 /**
  * <p>
- * TODO comment
+ * represents a serializable, clonable, iterable representation of a read only list of task
+ * instances. The list is ordered. It does not provide methods for changing it.
  * </p>
  * 
@@ -27 +28 @@
 
     /**
-     *
+     * <p>
+     * returns the task instance at the position with the given index. May throw an exception
+     * if the index is invalid.
+     * </p>
+     * 
+     * @param index the index of the task instance to be returned
+     * 
+     * @return the task instance at the given index
      */
     public ITaskInstance get(int index);
 
     /**
-     *
+     * <p>
+     * returns the size of the list, i.e. the number of task instances in the list
+     * </p>
+     * 
+     * @return as described
      */
     public int size();
 
     /**
-     *
+     * <p>
+     * clones a task instance list by creating exact clones of each contained instance in their
+     * order
+     * </p>
+     * 
+     * @return a clone of the task instance list
      */
     public ITaskInstanceList clone();

trunk/autoquest-core-tasktrees/src/main/java/de/ugoe/cs/autoquest/tasktrees/treeifc/IUserSession.java

@@ -19 +19 @@
 /**
  * <p>
- * TODO comment
+ * A user session represents task executions, i.e. a task instances of a specific user that were
+ * executed in a coherent manner. Therefore, they are an ordered list of task instances where
+ * the order denotes the order of the task executions.
  * </p>
  * 
@@ -27 +29 @@
 
     /**
-     *
+     * <p>
+     * returns the list of task instances executed in the represented session.
+     * </p>
+     * 
+     * @return as described
      */
     public List<ITaskInstance> getExecutedTasks();
     
     /**
-     *
+     * <p>
+     * compares the user session with another one. Two user sessions are only equal, if they
+     * contain the same number of task instances and if each task instance at each position is
+     * equal to the respective other session. 
+     * </p>
+     * 
+     * @param userSession the session to compare the session to
+     * 
+     * @return true if both sessions are equal, false else
      */
     public boolean equals(IUserSession userSession);
 
     /**
-     *
+     * <p>
+     * returns a hash code for the session to be able to store the session in a hash map.
+     * </p>
+     * 
+     * @return as described
      */
     public int hashCode();
 
     /**
-     *
+     * <p>
+     * clones a user session by creating exact clones of each contained instance in their order
+     * </p>
+     * 
+     * @return a clone of the session
      */
     public IUserSession clone();