Document support package

subprojects/testfx-core/src/main/java/org/testfx/service/support/Capture.java

@@ -18,6 +18,10 @@
 
 import javafx.scene.image.Image;
 
+/**
+ * Essentially a {@link java.util.function.Supplier} that returns an {@link Image} via {@link #getImage()}
+ */
+@FunctionalInterface
 public interface Capture {
 
     Image getImage();

subprojects/testfx-core/src/main/java/org/testfx/service/support/CaptureSupport.java

@@ -28,18 +28,37 @@ public interface CaptureSupport {
     // METHODS.
     //---------------------------------------------------------------------------------------------
 
+    /**
+     * Returns a snapshot of the node
+     */
     Image captureNode(Node node);
 
+    /**
+     * Returns a screenshot of the given region
+     */
     Image captureRegion(Rectangle2D region);
 
+    /**
+     * Loads the image file from the given path
+     */
     Image loadImage(Path path);
 
+    /**
+     * Saves the given image to the given path
+     */
     void saveImage(Image image,
                    Path path);
 
+    /**
+     * NOT YET IMPLEMENTED
+     */
     Image annotateImage(Shape shape,
                         Image image);
 
+    /**
+     * Compares two images and returns a {@link PixelMatcherResult} that defines
+     * the how similar/dissimilar one was from the other.
+     */
     PixelMatcherResult matchImages(Image image0,
                                    Image image1,
                                    PixelMatcher pixelMatcher);

subprojects/testfx-core/src/main/java/org/testfx/service/support/PixelMatcher.java

@@ -22,18 +22,33 @@
 
 public interface PixelMatcher {
 
+    /**
+     * Returns a {@link PixelMatcherResult} that indicates how similar/dissimilar the two images were.
+     */
     PixelMatcherResult match(Image image0,
                              Image image1);
 
+    /**
+     * Returns true if {@code color0} is close enough to {@code color1} as determined by a color distance/factor.
+     */
     boolean matchColors(Color color0,
                         Color color1);
 
+    /**
+     * Creates a new {@link WritableImage} using {@code image0}'s width and {@code image1}'s height
+     */
     WritableImage createEmptyMatchImage(Image image0,
                                         Image image1);
 
+    /**
+     * Creates a color that represents a match between the two images' pixels
+     */
     Color createMatchColor(Color color0,
                            Color color1);
 
+    /**
+     * Creates a color that represents a mismatch between the two images' pixels
+     */
     Color createNonMatchColor(Color color0,
                               Color color1);
 

subprojects/testfx-core/src/main/java/org/testfx/service/support/PixelMatcherResult.java

@@ -18,6 +18,10 @@
 
 import javafx.scene.image.Image;
 
+/**
+ * Indicates how similar/dissimilar two images were on a pixel-to-pixel comparison level via
+ * {@link PixelMatcher#match(Image, Image)}.
+ */
 public class PixelMatcherResult {
 
     //---------------------------------------------------------------------------------------------
@@ -48,26 +52,44 @@ public PixelMatcherResult(Image matchImage,
     // METHODS.
     //---------------------------------------------------------------------------------------------
 
+    /**
+     * Gets the image whose pixels indicate matches and mismatches between the two original images.
+     */
     public Image getMatchImage() {
         return matchImage;
     }
 
+    /**
+     * Gets the total number of pixels in the match image
+     */
     public long getTotalPixels() {
         return totalPixels;
     }
 
+    /**
+     * Gets the total number of pixels that matched between the two original images.
+     */
     public long getMatchPixels() {
         return matchPixels;
     }
 
+    /**
+     * Gets the total number of pixels that did not match between the two original images.
+     */
     public long getNonMatchPixels() {
         return totalPixels - matchPixels;
     }
 
+    /**
+     * Gets the percentage of pixels that matched between the two original images
+     */
     public double getMatchFactor() {
         return matchFactor;
     }
 
+    /**
+     * Gets the percentage of pixels that did not match between the two original images
+     */
     public double getNonMatchFactor() {
         return 1.0 - matchFactor;
     }

subprojects/testfx-core/src/main/java/org/testfx/service/support/WaitUntilSupport.java

@@ -26,13 +26,26 @@
 import org.testfx.api.annotation.Unstable;
 import org.testfx.util.WaitForAsyncUtils;
 
+/**
+ * Provides methods that will wait for a given node or value to meet a given condition by repeatedly testing that item
+ * until the condition is met or the timeout is reached. When the timeout is reached, a {@link RuntimeException} is
+ * thrown.
+ */
 @Unstable(reason = "needs more tests")
 public class WaitUntilSupport {
 
     //---------------------------------------------------------------------------------------------
     // METHODS.
     //---------------------------------------------------------------------------------------------
 
+    /**
+     * Waits until the provided node fulfills the given condition.
+     *
+     * @param node the node
+     * @param condition the condition
+     * @param timeoutInSeconds the number of seconds to wait before timing out. If the time out is reached, a
+     *                         {@link RuntimeException} is thrown.
+     */
     public <T extends Node> void waitUntil(final T node,
                                            final Predicate<T> condition,
                                            int timeoutInSeconds) {
@@ -51,12 +64,28 @@ public void waitUntil(final Node node,
         awaitCondition(() -> condition.matches(node), timeoutInSeconds);
     }
 
+    /**
+     * Waits until the provided value fulfills the given condition.
+     *
+     * @param value the value
+     * @param condition the condition
+     * @param timeoutInSeconds the number of seconds to wait before timing out. If the time out is reached, a
+     *                         {@link RuntimeException} is thrown.
+     */
     public <T> void waitUntil(final T value,
                               final Matcher<? super T> condition,
                               int timeoutInSeconds) {
         awaitCondition(() -> condition.matches(value), timeoutInSeconds);
     }
 
+    /**
+     * Waits until the provided callable fulfills the given condition.
+     *
+     * @param callable the callable
+     * @param condition the condition
+     * @param timeoutInSeconds the number of seconds to wait before timing out. If the time out is reached, a
+     *                         {@link RuntimeException} is thrown.
+     */
     public <T> void waitUntil(final Callable<T> callable,
                               final Matcher<? super T> condition,
                               int timeoutInSeconds) {