Add javadoc; fix typo

Author: glibas

src/main/java/com/assertthat/selenium_screenshotter/core/PageScreenshot.java

@@ -17,43 +17,57 @@ public class PageScreenshot extends Screenshot<PageScreenshot> {
     }
 
     /**
-     * @param element
-     * @return
+     * Highlights WebElement within the page with Color.red
+     * and line width 3.
+     *
+     * @param element WebElement to be highlighted
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot highlight(WebElement element) {
         highlight(element, Color.red, 3);
         return this;
     }
 
     /**
-     * @param element
-     * @param color
-     * @param lineWidth
-     * @return
+     * Highlights WebElement within the page with provided color
+     * and line width.
+     *
+     * @param element WebElement to be highlighted
+     * @param color color of the line
+     * @param lineWidth width of the line
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot highlight(WebElement element, Color color, int lineWidth) {
         image = ImageProcessor.highlight(image, new Coordinates(element), color, lineWidth);
         return this;
     }
 
     /**
-     * @param element
-     * @param text
-     * @return
+     * Highlight WebElement within the page (same as in {@link #highlight(WebElement)}}
+     * and adding provided text above highlighted element.
+     *
+     * @param element WebElement to be highlighted with Color.red
+     *                and line width 3
+     * @param text test to be places above highlighted element with
+     *             Color.red, font "Serif", BOLD, size 20
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot highlightWithText(WebElement element, String text) {
         highlightWithText(element, Color.red, 3, text, Color.red, new Font("Serif", Font.BOLD, 20));
         return this;
     }
 
     /**
-     * @param element
-     * @param elementColor
-     * @param lineWidth
-     * @param text
-     * @param textColor
-     * @param textFont
-     * @return
+     * Highlight WebElement within the page, same as in {@link #highlight(WebElement)}
+     * but providing ability to override default color, font values.
+     *
+     * @param element WebElement to be highlighted
+     * @param elementColor element highlight color
+     * @param lineWidth line width around the element
+     * @param text text to be placed above the highlighted element
+     * @param textColor color of the text
+     * @param textFont text font
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot highlightWithText(WebElement element, Color elementColor, int lineWidth, String text, Color textColor, Font textFont) {
         highlight(element, elementColor, 0);
@@ -63,34 +77,43 @@ public PageScreenshot highlightWithText(WebElement element, Color elementColor,
     }
 
     /**
-     * @return
+     * Blur the entire page.
+     *
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot blur() {
         image = ImageProcessor.blur(image);
         return this;
     }
 
     /**
-     * @param element
-     * @return
+     * Blur provided element within the page only.
+     *
+     * @param element WebElement to be blurred
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot blur(WebElement element) {
         image = ImageProcessor.blurArea(image, new Coordinates(element));
         return this;
     }
 
     /**
-     * @param element
-     * @return
+     * Makes an element withing a page 'monochrome' - applies gray-and-white filter.
+     * Original colors remain on the rest of the page.
+     *
+     * @param element WebElement within the page to be made 'monochrome'
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot monochrome(WebElement element) {
         image = ImageProcessor.monochromeArea(image, new Coordinates(element));
         return this;
     }
 
     /**
-     * @param element
-     * @return
+     * Blurs all the page except the element provided.
+     *
+     * @param element WebElement to stay not blurred
+     * @return instance of type PageScreenshot
      */
     public PageScreenshot blurExcept(WebElement element) {
         image = ImageProcessor.blurExceptArea(image, new Coordinates(element));

src/main/java/com/assertthat/selenium_screenshotter/core/Screenshot.java

@@ -30,10 +30,9 @@ public abstract class Screenshot<T extends Screenshot<T>> {
     private String title;
 
     /**
-     * Make screenshot of the viewport only
-     * <p>
+     * Make screenshot of the viewport only.
      * To be used when screenshotting the page
-     * and don't need to scroll while making screenshots (FF, IE)
+     * and don't need to scroll while making screenshots (FF, IE).
      *
      * @param driver WebDriver instance
      * @return PageScreenshot instance
@@ -48,7 +47,7 @@ public static PageScreenshot page(WebDriver driver) {
     /**
      * To be used when screenshotting the page
      * and need to scroll while making screenshots, either vertically or
-     * horizontally or both directions (Chrome)
+     * horizontally or both directions (Chrome).
      *
      * @param driver WebDriver instance
      * @param scroll ScrollStrategy How you need to scroll
@@ -71,7 +70,7 @@ public static PageScreenshot page(WebDriver driver, ScrollStrategy scroll) {
     }
 
     /**
-     * To be used when need to screenshot particular element
+     * To be used when need to screenshot particular element.
      *
      * @param driver  WebDriver instance
      * @param element WebElement instance to be screenshotted
@@ -90,7 +89,7 @@ public static ElementScreenshot element(WebDriver driver, WebElement element) {
 
     /**
      * @param name file name of the resulted image
-     *             by default will be timestamp in format: 'yyyy_MM_dd_HH_mm_ss_SSS'
+     *             by default will be timestamp in format: 'yyyy_MM_dd_HH_mm_ss_SSS'.
      * @return instance of type Screenshot
      */
     public T withName(String name) {
@@ -102,7 +101,7 @@ public T withName(String name) {
 
     /**
      * @param title title of the resulted image.
-     *              Won't be assigned by default
+     *              Won't be assigned by default.
      * @return instance of type Screenshot
      */
     public T withTitle(String title) {
@@ -111,7 +110,7 @@ public T withTitle(String title) {
     }
 
     /**
-     * Apply gray-and-white filter to the image
+     * Apply gray-and-white filter to the image.
      *
      * @return instance of type Screenshot
      */
@@ -121,7 +120,7 @@ public T monochrome() {
     }
 
     /**
-     * @return
+     * @return BufferedImage - current image being processed.
      */
     public BufferedImage getImage() {
         return image;
@@ -133,7 +132,7 @@ protected void setImage(BufferedImage image) {
 
     /**
      * Final method to be called in the chain.
-     * Actually saves processed image.
+     * Actually saves processed image to the default location: ./screenshots
      */
     public void save() {
         File screenshotFile = new File(location.toString(), fileName);
@@ -145,7 +144,7 @@ public void save() {
 
     /**
      * Final method to be called in the chain.
-     * Actually saves processed image.
+     * Actually saves processed image to the specified path.
      */
     public void save(String location) {
         File screenshotFile = new File(location, fileName);
@@ -157,7 +156,7 @@ public void save(String location) {
 
     /**
      * Final method to be called in the chain.
-     * Actually saves processed image.
+     * Actually saves processed image to the specified path.
      */
     public void save(Path location) {
         File screenshotFile = new File(location.toString(), fileName);
@@ -182,8 +181,9 @@ public boolean equals(Object o, double deviation) {
     }
 
     /**
-     * @param o
-     * @return
+     * @param o Object to compare with
+     * @return true if the the provided object is of type Screenshot
+     * and images are strictly equal.
      */
     @Override
     public boolean equals(Object o) {
@@ -196,22 +196,23 @@ public boolean equals(Object o) {
     }
 
     /**
-     * @param image
-     * @return
+     * @param image BufferedImage to compare with.
+     * @return true if the the provided image and current image are strictly equal.
      */
     public boolean equals(BufferedImage image) {
         if (this.getImage() == image) return true;
         return getImage() != null ? ImageProcessor.imagesAreEquals(getImage(), image, 0) : image == null;
     }
 
     /**
-     * @param image
-     * @param deviation
-     * @return
+     * @param image BufferedImage to compare with.
+     * @param deviation allowed deviation while comparing.
+     * @return true if the the percentage of differences
+     * between current image and provided one is less than or equal to <b>deviation</b>
      */
     public boolean equals(BufferedImage image, double deviation) {
         if (this.getImage() == image) return true;
-        return getImage() != null ? ImageProcessor.imagesAreEquals(getImage(), image, 0) : image == null;
+        return getImage() != null ? ImageProcessor.imagesAreEquals(getImage(), image, deviation) : image == null;
     }
 
     /**