- * TODO: comment - *
- * - * @param guiStructure + * dumps the GUI structure provided by the parameter into the log file. Calls itself + * recursively to traverse the GUI structure. + * + * + * @param guiStructure the GUI structure to be logged */ private void dumpGuiStructure(HtmlPageElement guiStructure) { @@ -267,9 +268,12 @@ /** *- * TODO: comment - *
- * - * @param string - * @param integer + * dumps a parameter with the given name and value to the log file. The result is a + * tag named param with a name attribute and a value attribute. The value is transformed + * to a String if it is no String already. Furthermore, an XML entity replacement is performed + * if required. + * + * + * @param name the name of the parameter to be dumped + * @param value the value of the parameter to be dumped */ private void dumpParam(String name, Object value) { Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java (revision 1021) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java (revision 1022) @@ -333,10 +333,12 @@ /** *- * TODO: comment - *
- * - * @param message - * @param clientInfos - * @return + * extracts the GUI structure from the provided JSON object. + * + * + * @param object the JSON object to extract the GUI structure from + * @param clientInfos infos about the client who send the data + * + * @return the GUI structure extracted from the JSON object of which the root node is a + * representation of the server of the HTML page that was observed */ private HtmlPageElement extractHtmlPageElements(JSONObject object, @@ -354,9 +356,11 @@ /** *- * TODO: comment - *
- * - * @param clientInfos - * @return + * instantiates an element of the GUI structure representing the server of the observed + * web page + * + * + * @param clientInfos infos about the client who send the data + * + * @return as described */ private HtmlPageElement getServerElement(HtmlClientInfos clientInfos) { @@ -371,8 +375,12 @@ /** *- * TODO: comment - *
- * - * @param clientInfos + * instantiates an element of the GUI structure representing the observed web page. Adds + * this element to the provided server as child. + * + * + * @param clientInfos infos about the client who send the data + * @param server the server on which the page represented by the return value resists + * + * @return as described */ private HtmlPageElement getPageElementRepresentingWebPage(HtmlClientInfos clientInfos, @@ -395,9 +403,13 @@ /** *- * TODO: comment - *
- * - * @param jsonPageElement - * @return + * converts a JSON object representing an HTML page element to an HTML page element. Calls + * itself recursively to also convert the children of the element, if any. + * + * + * @param jsonPageElement the JSON object to be converted + * @param parentPath the path through the DOM of the parent HTML page element of the + * converted one + * + * @return as described. */ private HtmlPageElement convert(JSONObject jsonPageElement, String parentPath) { Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlPageElement.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlPageElement.java (revision 1021) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlPageElement.java (revision 1022) @@ -20,5 +20,6 @@ /** *- * TODO comment + * represents an element of an HTML GUI. This can be a server, which is usually the root of a + * GUI structure, a web page, or a tag within a web page. *
* @@ -28,30 +29,33 @@ /** - * + * path to the parent of this page element or null, if this is the root element */ private String parentPath; /** - * + * the name of the tag represented by this page element. May also be the name of the server + * or the page. */ private String tagName; /** - * + * the id of the page element. May also be the name of the server including port number or the + * URL of the page */ private String id; /** - * + * the title of the page if a page is represented through this element */ private String title; /** - * + * the index of this element regarding all elements with the same tag name in the list of + * children of the parent element */ private Integer index; /** - * + * the children of this element */ private List- * TODO: comment - *
- * - * @param tagName - * @param index - * @param id - * @param children + * instantiates a new element representing a tag in an HTML page + * + * + * @param parentPath the path through the DOM to the parent node of the represented tag + * @param tagName the name of the represented tag + * @param id the id of the tag in the DOM + * @param index the index of the represented tag regarding all tags with the same tag name + * in the list of children of the parent tag */ HtmlPageElement(String parentPath, String tagName, String id, Integer index) { @@ -76,11 +81,13 @@ /** *- * TODO: comment - *
- * - * @param tagName - * @param index - * @param id - * @param children + * instantiates a new element representing an HTML page + * + * + * @param parentPath the path through the DOM to the parent node of the represented tag which is + * usually a server + * @param tagName the name of the represented tag which is the path of the web page + * @param title the title of the web page + * @param id the id of the web page which is its path + * @param index usually 0 */ HtmlPageElement(String parentPath, String tagName, String id, String title, Integer index) { @@ -90,4 +97,9 @@ /** + *+ * returns the name of the tag represented by this page element. May also be the name of the + * server or the page. + *
+ * * @return the tagName */ @@ -97,4 +109,9 @@ /** + *+ * returns the id of the page element. May also be the name of the server including port + * number or the URL of the page + *
+ * * @return the id */ @@ -104,4 +121,8 @@ /** + *+ * returns the title of the page if a page is represented through this element + *
+ * * @return the title */ @@ -111,4 +132,9 @@ /** + *+ * returns the index of this element regarding all elements with the same tag name in the list + * of children of the parent element + *
+ * * @return the index */ @@ -118,4 +144,8 @@ /** + *+ * returns the children of this element if any, null else + *
+ * * @return the children */ @@ -126,5 +156,7 @@ /** - * + * adds a child to this element + * + * @param child the child to be added */ void addChild(HtmlPageElement child) { @@ -140,8 +172,8 @@ /** *- * TODO: comment - *
- * - * @return + * returns the path to the parent of this page element or null, if this is the root element + * + * + * @return as described */ String getParentPath() { @@ -151,8 +183,10 @@ /** *- * TODO: comment - *
- * - * @return + * calculates and returns the path to the represented page element through the DOM. Includes + * the parent path if any. The represented element is included in the path with its tag name + * and its id if it has one, or its index. + * + * + * @return as described */ String getPath() { Index: trunk/autoquest-htmlmonitor/src/main/js/autoquest-htmlmonitor.js =================================================================== --- trunk/autoquest-htmlmonitor/src/main/js/autoquest-htmlmonitor.js (revision 1021) +++ trunk/autoquest-htmlmonitor/src/main/js/autoquest-htmlmonitor.js (revision 1022) @@ -342,5 +342,12 @@ /** - * TODO comment + * adds event handling functionality to the provided node. Calls + * {@link #addEventHandlingWithJQuery(node,parentPath)} or + * {@link #addEventHandlingWithoutJQuery(node,parentPath)} depending on the fact if jQuery is + * available and must therefore be used, or not. + * + * @param node the node of the DOM structure that shall be equipped with event handling + * @param parentPath the path to the parent node of the provided node within the DOM-structure of + * the HTML-site */ function addEventHandling(node, parentPath) { @@ -354,5 +361,9 @@ /** - * TODO comment + * adds event handling functionality to the provided node using onxxx attributes + * + * @param node the node of the DOM structure that shall be equipped with event handling + * @param parentPath the path to the parent node of the provided node within the DOM-structure of + * the HTML-site */ function addEventHandlingWithoutJQuery(node, parentPath) { @@ -372,5 +383,10 @@ /** - * TODO comment + * adds event handling functionality to the provided node using jQuery attributes. If the node + * already used onxxx attributes, these are extended instead of using jQuery. + * + * @param node the node of the DOM structure that shall be equipped with event handling + * @param parentPath the path to the parent node of the provided node within the DOM-structure of + * the HTML-site */ function addEventHandlingWithJQuery(node, parentPath) { @@ -406,5 +422,12 @@ /** - * TODO comment + * adapts the event handling attributed provided by the action parameter so that it calls + * the {@link #handleEvent(node, action, path, even)} function in the case the event occurs. + * Either the method creates an appropriate onxxx attribute on the node if there is none, or it + * adds a call to the function as first thing called by the onxxx attribute. + * + * @param node the node of the DOM structure that shall be equipped with event handling + * @param nodePath the path to node within the DOM-structure of the HTML-site + * @param action the event for which event handling shall be enabled */ function adaptEventHandlingAttribute(node, nodePath, action) {