Add basic documentation to Robot classes

subprojects/testfx-core/src/main/java/org/testfx/robot/BaseRobot.java

@@ -33,6 +33,10 @@ public void typeKeyboard(Scene scene,
                              KeyCode key,
                              String character);
 
+    /**
+     *
+     * @return the current mouse location
+     */
     public Point2D retrieveMouse();
 
     public void moveMouse(Point2D point);
@@ -43,8 +47,16 @@ public void typeKeyboard(Scene scene,
 
     public void releaseMouse(MouseButton button);
 
+    /**
+     *
+     * @param region the given bounds for the image
+     * @return a screen shot of the given region
+     */
     public Image captureRegion(Rectangle2D region);
 
+    /**
+     * Calls {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()}
+     */
     public void awaitEvents();
 
 }

subprojects/testfx-core/src/main/java/org/testfx/robot/ClickRobot.java

@@ -22,13 +22,35 @@
 
 public interface ClickRobot {
 
+    /**
+     * Clicks whatever is under the mouse.
+     *
+     * @param buttons the mouse buttons to click
+     */
     public void clickOn(MouseButton... buttons);
 
+    /**
+     * Moves mouse to {@link PointQuery#query()} and clicks whatever is under it.
+     *
+     * @param pointQuery the pointQuery
+     * @param buttons the mouse buttons to click
+     */
     public void clickOn(PointQuery pointQuery,
                         MouseButton... buttons);
 
+    /**
+     * Double-clicks whatever is under the mouse.
+     *
+     * @param buttons the mouse buttons to click
+     */
     public void doubleClickOn(MouseButton... buttons);
 
+    /**
+     * Moves mouse to {@link PointQuery#query()} and double-clicks whatever is under it.
+     *
+     * @param pointQuery the pointQuery
+     * @param buttons the mouse buttons to click
+     */
     public void doubleClickOn(PointQuery pointQuery,
                               MouseButton... buttons);
 

subprojects/testfx-core/src/main/java/org/testfx/robot/DragRobot.java

@@ -22,15 +22,41 @@
 
 public interface DragRobot {
 
+    /**
+     * Presses the given mouse button(s) on whatever is under the mouse's current location.
+     *
+     * @param buttons the mouse buttons to press
+     */
     public void drag(MouseButton... buttons);
 
+    /**
+     * Moves the mouse to {@link PointQuery#query()} before presses the given mouse button(s) on whatever is under
+     * the mouse's new location.
+     *
+     * @param pointQuery the pointQuery
+     * @param buttons the mouse buttons to press
+     */
     public void drag(PointQuery pointQuery,
                      MouseButton... buttons);
 
+    /**
+     * Releases the mouse at current position.
+     */
     public void drop();
 
+    /**
+     * Moves the mouse to {@link PointQuery#query()} before releasing the mouse.
+     *
+     * @param pointQuery the pointQuery
+     */
     public void dropTo(PointQuery pointQuery);
 
+    /**
+     * Moves the mouse horizontally by {@code x} and vertically by {@code y} before releasing the mouse.
+     *
+     * @param x the amount by which to move the mouse horizontally
+     * @param y the amount by which to move the mouse vertically
+     */
     public void dropBy(double x,
                        double y);
 

subprojects/testfx-core/src/main/java/org/testfx/robot/KeyboardRobot.java

@@ -22,25 +22,42 @@
 public interface KeyboardRobot {
 
     /**
-     * Presses given keys, until explicitly released.
+     * Presses given keys, until explicitly released via {@link #release(KeyCode...)}. Once pressed,
+     * {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is called.
      *
      * @param keys the key codes
      */
     public void press(KeyCode... keys);
+
+    /**
+     * Presses given keys, until explicitly released via {@link #release(KeyCode...)}.
+     * {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is not called.
+     *
+     * @param keys the key codes
+     */
     public void pressNoWait(KeyCode... keys);
 
     /**
      * Gets the keys that have been pressed and not released.
+     *
      * @return an unmodifiable set of the keys that have been pressed but not released.
      */
     public Set<KeyCode> getPressedKeys();
 
     /**
-     * Releases given keys.
+     * Releases given keys. Once released, {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is called.
+     * <em>Note:</em> passing in an empty {@code KeyCode[]} will release all pressed keys.
      *
      * @param keys the key codes
      */
     public void release(KeyCode... keys);
+
+    /**
+     * Releases given keys. {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is not called.
+     * <em>Note:</em> passing in an empty {@code KeyCode[]} will release all pressed keys.
+     *
+     * @param keys the key codes
+     */
     public void releaseNoWait(KeyCode... keys);
 
 }

subprojects/testfx-core/src/main/java/org/testfx/robot/MouseRobot.java

@@ -24,11 +24,21 @@
 public interface MouseRobot {
 
     /**
-     * Presses given buttons, until explicitly released.
+     * Presses given buttons, until explicitly released via {@link #release(MouseButton...)}. Once pressed,
+     * calls {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()}.
+     * <em>Note:</em> passing in an empty {@code MouseButton[]} will call {@code press(MouseButton.PRIMARY)}.
      *
      * @param buttons the mouse buttons
      */
     public void press(MouseButton... buttons);
+
+    /**
+     * Presses given buttons, until explicitly released via {@link #release(MouseButton...)}. Once pressed,
+     * {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is not called.
+     * <em>Note:</em> passing in an empty {@code MouseButton[]} will call {@code press(MouseButton.PRIMARY)}.
+     *
+     * @param buttons the mouse buttons
+     */
     public void pressNoWait(MouseButton... buttons);
 
     /**
@@ -38,27 +48,50 @@ public interface MouseRobot {
     public Set<MouseButton> getPressedButtons();
 
     /**
-     * Releases given buttons.
+     * Releases given buttons. Once pressed, calls {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()}.
+     * <em>Note:</em> passing in an empty {@code MouseButton[]} will release all pressed {@code MouseButton}s.
      *
      * @param buttons the mouse buttons
      */
     public void release(MouseButton... buttons);
+
+    /**
+     * Releases given buttons. Once pressed, {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is not called.
+     * <em>Note:</em> passing in an empty {@code MouseButton[]} will release all pressed {@code MouseButton}s.
+     *
+     * @param buttons the mouse buttons
+     */
     public void releaseNoWait(MouseButton... buttons);
 
     /**
-     * Moves mouse to given location.
+     * Moves mouse to given location. Once moved, calls {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()}.
      *
      * @param location the location to move
      */
     public void move(Point2D location);
+
+    /**
+     * Moves mouse to given location. Once moved, {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is
+     * not called.
+     *
+     * @param location the location to move
+     */
     public void moveNoWait(Point2D location);
 
     /**
-     * Scrolls mouse wheel given amount.
+     * Scrolls mouse wheel by the given amount. Once scrolled, calls
+     * {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()}.
      *
      * @param wheelAmount the amount to scroll
      */
     public void scroll(int wheelAmount);
+
+    /**
+     * Scrolls mouse wheel by the given amount. Once scrolled,
+     * {@link org.testfx.util.WaitForAsyncUtils#waitForFxEvents()} is not called.
+     *
+     * @param wheelAmount the amount to scroll
+     */
     public void scrollNoWait(int wheelAmount);
 
 }

subprojects/testfx-core/src/main/java/org/testfx/robot/MoveRobot.java

@@ -20,8 +20,20 @@
 
 public interface MoveRobot {
 
+    /**
+     * Moves mouse to {@link PointQuery#query()}.
+     *
+     * @param pointQuery the pointQuery
+     */
     public void moveTo(PointQuery pointQuery);
 
+    /**
+     * Moves mouse from current location to new location by {@code x} on the horizontal axis and by {@code y} on
+     * the vertical axis.
+     *
+     * @param x the amount by which to move the mouse horizontally
+     * @param y the amount by which to move the mouse vertically
+     */
     public void moveBy(double x,
                        double y);
 

subprojects/testfx-core/src/main/java/org/testfx/robot/ScrollRobot.java

@@ -21,19 +21,56 @@
 
 public interface ScrollRobot {
 
+    /**
+     * Scrolls vertically by amount (in terms of ticks of a mouse wheel): if {@code amount >= 0}, up; otherwise, down.
+     *
+     * @param amount of a mouse wheel's scroll ticks
+     */
     void scroll(int amount);
 
+    /**
+     * Scrolls vertically by amount (in terms of ticks of a mouse wheel) in given direction.
+     *
+     * @param positiveAmount the number of scroll ticks
+     * @param direction whether to scroll up or down
+     */
     void scroll(int positiveAmount,
                 VerticalDirection direction);
 
+    /**
+     * Scrolls up by amount (in terms of ticks of a mouse wheel).
+     * .
+     * @param positiveAmount the number of scroll ticks
+     */
     void scrollUp(int positiveAmount);
 
+    /**
+     * Scrolls down by amount (in terms of ticks of a wheel).
+     *
+     * @param positiveAmount the number of scroll ticks
+     */
     void scrollDown(int positiveAmount);
 
+    /**
+     * Scrolls horizontally by amount (in terms of ticks of a mouse wheel) in given direction.
+     *
+     * @param positiveAmount the number of scroll ticks
+     * @param direction whether to scroll left or right
+     */
     void scroll(int positiveAmount,
                 HorizontalDirection direction);
 
+    /**
+     * Scrolls left by amount (in terms of ticks of a wheel).
+     *
+     * @param positiveAmount the number of scroll ticks
+     */
     void scrollLeft(int positiveAmount);
 
+    /**
+     * Scrolls right by amount (in terms of ticks of a wheel).
+     *
+     * @param positiveAmount the number of scroll ticks
+     */
     void scrollRight(int positiveAmount);
 }