Fixing comments from @amuniz

test/src/main/java/com/gargoylesoftware/htmlunit/WebClientUtil.java

@@ -30,25 +30,48 @@ import java.net.MalformedURLException;
 import java.net.URL;
 
 /**
+ * {@link WebClient} helper methods.
  * @author <a href="mailto:tom.fennelly@gmail.com">tom.fennelly@gmail.com</a>
  */
 public class WebClientUtil {
 
+    /**
+     * Wait for all async JavaScript tasks associated with the supplied {@link WebClient} instance
+     * to complete.
+     * <p>
+     * Waits for 10 seconds before timing out.
+     * @param webClient The {@link WebClient} instance.
+     */
     public static void waitForJSExec(WebClient webClient) {
         waitForJSExec(webClient, 10000);
     }
 
+    /**
+     * Wait for all async JavaScript tasks associated with the supplied {@link WebClient} instance
+     * to complete.
+     * @param webClient The {@link WebClient} instance.
+     * @param timeout The timeout in milliseconds.                  
+     */
     public static void waitForJSExec(WebClient webClient, long timeout) {
         webClient.getJavaScriptEngine().processPostponedActions();
         webClient.waitForBackgroundJavaScript(timeout);
     }
 
+    /**
+     * Create and add an {@link ExceptionListener} to the {@link WebClient} instance.
+     * @param webClient The {@link WebClient} instance.
+     * @return The {@link ExceptionListener}.
+     */
     public static ExceptionListener addExceptionListener(WebClient webClient) {
         ExceptionListener exceptionListener = new ExceptionListener(webClient);
         webClient.setJavaScriptErrorListener(exceptionListener);
         return exceptionListener;
     }
 
+    /**
+     * JavaScript Exception listener.
+     * @see #addExceptionListener(WebClient)
+     */
     public static class ExceptionListener implements JavaScriptErrorListener {
 
         private final WebClient webClient;
@@ -58,31 +81,57 @@ public class WebClientUtil {
             this.webClient = webClient;
         }
 
+        /**
+         * Get the last {@link ScriptException}.
+         * @return The last {@link ScriptException}, or {@code null} if none happened.
+         */
         public ScriptException getScriptException() {
             return scriptException;
         }
 
+        /**
+         * Get the last {@link ScriptException}.
+         * <p>
+         * Performs a call to {@link #assertHasException()}.
+         * @return The last {@link ScriptException}.
+         */
         public ScriptException getExpectedScriptException() {
             assertHasException();
             return scriptException;
         }
 
+        /**
+         * {@inheritDoc}
+         */
         @Override
         public void scriptException(InteractivePage htmlPage, ScriptException scriptException) {
             this.scriptException = scriptException;
         }
 
+        /**
+         * Assert that a {@link ScriptException} occurred within the JavaScript executing
+         * on the associated {@link WebClient}.
+         */
         public void assertHasException() {
             WebClientUtil.waitForJSExec(webClient);
             Assert.assertNotNull("A JavaScript Exception was expected.", scriptException);
         }
 
+        /**
+         * {@inheritDoc}
+         */
         @Override
         public void timeoutError(InteractivePage htmlPage, long allowedTime, long executionTime) {
         }
+        /**
+         * {@inheritDoc}
+         */
         @Override
         public void malformedScriptURL(InteractivePage htmlPage, String url, MalformedURLException malformedURLException) {
         }
+        /**
+         * {@inheritDoc}
+         */
         @Override
         public void loadScriptError(InteractivePage htmlPage, URL scriptUrl, Exception exception) {
         }

test/src/main/java/com/gargoylesoftware/htmlunit/html/DomNodeUtil.java

@@ -29,19 +29,38 @@ import com.gargoylesoftware.htmlunit.html.xpath.XPathUtils;
 import java.util.List;
 
 /**
+ * {@link DomNode} helper methods.
+ * 
  * @author <a href="mailto:tom.fennelly@gmail.com">tom.fennelly@gmail.com</a>
  */
 public class DomNodeUtil {
 
-    public static <E> List<E> getByXPath(final DomNode domNode, final String xpathExpr) {
+    /**
+     * Evaluates an XPath expression from the specified node, returning the resultant nodes.
+     * <p>
+     * Calls {@link WebClientUtil#waitForJSExec(com.gargoylesoftware.htmlunit.WebClient)} before
+     * executing the query.
+     * 
+     * @param domNode the node to start searching from
+     * @param xpathExpr the XPath expression
+     * @return the list of objects found.
+     */
+    public static <E> List<E> selectNodes(final DomNode domNode, final String xpathExpr) {
         WebClientUtil.waitForJSExec(domNode.getPage().getWebClient());
         return (List) XPathUtils.getByXPath(domNode, xpathExpr, null);
     }
 
-    public static <E> List<E> selectNodes(final DomNode domNode, final String xpathExpr) {
-        return getByXPath(domNode, xpathExpr);
-    }
-
+    /**
+     * Evaluates the specified XPath expression from this node, returning the first matching element,
+     * or <tt>null</tt> if no node matches the specified XPath expression.
+     * <p>
+     * Calls {@link WebClientUtil#waitForJSExec(com.gargoylesoftware.htmlunit.WebClient)} before
+     * executing the query.
+     *
+     * @param domNode the node to start searching from
+     * @param xpathExpr the XPath expression
+     * @return the first element matching the specified XPath expression
+     */
     public static <X> X selectSingleNode(final DomNode domNode, final String xpathExpr) {
         WebClientUtil.waitForJSExec(domNode.getPage().getWebClient());
         return domNode.<X>getFirstByXPath(xpathExpr);

test/src/main/java/com/gargoylesoftware/htmlunit/html/HtmlElementUtil.java

@@ -23,22 +23,39 @@
  */
 package com.gargoylesoftware.htmlunit.html;
 
+import com.gargoylesoftware.htmlunit.Page;
 import com.gargoylesoftware.htmlunit.WebClient;
 import com.gargoylesoftware.htmlunit.WebClientUtil;
 
 import java.io.IOException;
 
 /**
+ * {@link HtmlElement} helper methods.
  * @author <a href="mailto:tom.fennelly@gmail.com">tom.fennelly@gmail.com</a>
  */
 public class HtmlElementUtil {
 
-    public static void click(HtmlElement element) throws IOException {
-        element.click();
-
-        // The JS script execution tasks are added to a queue and executed
-        // async. Wait for all to finish executing.
-        WebClient webClient = element.getPage().getWebClient();
-        WebClientUtil.waitForJSExec(webClient);
+    /**
+     * Click on the supplied element.
+     * <p>
+     * Waits for all executing JavaScript tasks to complete before returning.
+     *     
+     * @param element The element to click.
+     * @return The page resulting from the click
+     * @throws IOException if an IO error occurs
+     */
+    public static Page click(HtmlElement element) throws IOException {
+        if (element == null) {
+            return null;
+        }
+        
+        try {
+            return element.click();
+        } finally {
+            // The JS script execution tasks are added to a queue and executed
+            // async. Wait for all to finish executing.
+            WebClient webClient = element.getPage().getWebClient();
+            WebClientUtil.waitForJSExec(webClient);
+        }
     }
 }

test/src/main/java/com/gargoylesoftware/htmlunit/html/HtmlFormUtil.java

@@ -27,21 +27,37 @@ import com.gargoylesoftware.htmlunit.ElementNotFoundException;
 import com.gargoylesoftware.htmlunit.Page;
 import com.gargoylesoftware.htmlunit.WebClient;
 import com.gargoylesoftware.htmlunit.WebClientUtil;
-import com.gargoylesoftware.htmlunit.util.WebClientUtils;
 
 import java.io.IOException;
 import java.util.List;
 
 /**
+ * {@link HtmlForm} helper functions.
+ * 
  * @author <a href="mailto:tom.fennelly@gmail.com">tom.fennelly@gmail.com</a>
  */
 public class HtmlFormUtil {
 
+    /**
+     * Submit the supplied {@link HtmlForm}.
+     * <p>
+     * Locates the submit element/button on the form.
+     * @param htmlForm The {@link HtmlForm}.
+     * @return The submit result page.
+     * @throws IOException Error performing submit.
+     */
     public static Page submit(final HtmlForm htmlForm) throws IOException {
         HtmlElement submitElement = getSubmitButton(htmlForm);
         return submit(htmlForm, submitElement);
     }
 
+    /**
+     * Submit the supplied {@link HtmlForm} via the supplied submit element.
+     * @param htmlForm The {@link HtmlForm}.
+     * @param submitElement The element through which the submit should be performed.
+     * @return The submit result page.
+     * @throws IOException Error performing submit.
+     */
     public static Page submit(HtmlForm htmlForm, HtmlElement submitElement) throws IOException {
         final HtmlPage htmlPage = (HtmlPage) htmlForm.getPage();
         final WebClient webClient = htmlPage.getWebClient();
@@ -64,12 +80,10 @@ public class HtmlFormUtil {
                 Page resultPage = webClient.getCurrentWindow().getEnclosedPage();
 
                 if (resultPage == htmlPage) {
-                    // We're still on the same page (form submit didn't bring us anywhere).
-                    // Hackery. Seems like YUI is messing us about.
-                    return submitElement.click();
+                    return HtmlElementUtil.click(submitElement);
+                } else {
+                    return resultPage;
                 }
-
-                return resultPage;
             }
         } finally {
             // Make sure all background JS has executed.
@@ -107,6 +121,13 @@ public class HtmlFormUtil {
         return null;
     }
 
+    /**
+     * Get the form button having the specified text/caption.
+     * @param htmlForm The form containing the button.
+     * @param caption The button text/caption being searched for.
+     * @return The button if found.
+     * @throws ElementNotFoundException Failed to find the button on the form.
+     */
     public static HtmlButton getButtonByCaption(final HtmlForm htmlForm, final String caption) throws ElementNotFoundException {
         for (HtmlElement b : htmlForm.getHtmlElementsByTagName("button")) {
             if(b instanceof HtmlButton && b.getTextContent().trim().equals(caption)) {