Changeset 1076

Timestamp:

02/15/13 15:23:48 (12 years ago)

Author:

pharms

Message:

• removed TODOs

File:

• trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlGUIElementManager.java (modified) (7 diffs)

trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlGUIElementManager.java

@@ -25 +25 @@
 /**
  * <p>
- * TODO comment
+ * This class is used to calculate unique ids for GUI elements and to reuse GUI element objects.
+ * For this it provides appropriate create methods. If there is already a GUI element for the
+ * given parameters, it is reused. Otherwise, a new one is instantiated with a unique id and
+ * returned.
  * </p>
  * 
@@ -32 +35 @@
 class HtmlGUIElementManager {
 
-    /** */
+    /**
+     * an internal map for GUI elements and their respective ids.
+     */
     private Map<String, HtmlGUIElement> idMap = new HashMap<String, HtmlGUIElement>();
     
@@ -41 +46 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
+     * creates a new or reuses an existing GUI element representing a server
+     * </p>
+     * 
+     * @param name the name of the server to represent (must not be null)
+     * @param port the port on the server via which the communication is done
+     *
+     * @return a new or reuses an existing GUI element representing a server
      */
     HtmlServer createHtmlServer(String name, int port) {
@@ -68 +77 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
+     * creates a new or reuses an existing GUI element representing a document (web page)
+     * </p>
+     * 
+     * @param server the server on which the document resides (must not be null)
+     * @param path   the path of the document on the web server (every following the server spec
+     *               in the URL, must not be null)
+     * @param query  the query part of the URL pointing to the document
+     * @param title  the title of the document if available
+     *
+     * @return a new or reuses an existing GUI element representing a document
      */
     HtmlDocument createHtmlDocument(HtmlServer server, String path, String query, String title) {
@@ -98 +114 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param document
-     * @param parent
-     * @param tagName
-     * @param htmlid
-     * @param index
-     * @return
+     * creates a new or reuses an existing GUI element representing an HTML tag in a document
+     * </p>
+     * 
+     * @param document the document to which the HTML tag belongs (must not be null)
+     * @param parent   the parent tag, if any
+     * @param tagName  the name of the HTML tag (must not be null)
+     * @param htmlId   the document wide unique id of the tag, if available
+     * @param index    if no HTML id is present, the index of the tag regarding all children in
+     *                 the same parent having the same tag name. 
+     *
+     * @return a new or reuses an existing GUI element representing an HTML tag
      */
     HtmlPageElement createHtmlPageElement(HtmlDocument    document,
@@ -153 +171 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param document
-     * @param domPath
-     * @return
+     * determines the HTML tag belonging to the given document and residing in the document at the
+     * location denoted by the path. The path must be equal to the return value of the
+     * {@link HtmlPageElement#getDOMPath()} method.
+     * </p>
+     *
+     * @param document the document to which the searched tag belongs
+     * @param domPath  the path through the DOM where the searched tag resists
+     * 
+     * @return the appropriate HTML tag or null, if none is known
      */
     HtmlPageElement getPageElement(HtmlDocument document, String domPath) {
@@ -176 +197 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     *
-     * @param name
-     * @param string
-     * @return
+     * calculates a unique id for the given string fragments using SHA-512 and Base64 encoding.
+     * </p>
+     *
+     * @param fragments strings to be used for calculating a unique id
+     * 
+     * @return a Base64 encoded unique id for the provided fragments
      */
     private String calculateId(String... fragments) {