chore: Fix javadoc warnings (#1522)

vaadin · Aug 29, 2022 · 1d5c743 · 1d5c743
1 parent ea2d4a0
commit 1d5c743
Show file tree

Hide file tree

Showing 19 changed files with 86 additions and 19 deletions.
diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/ElementQuery.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/ElementQuery.java
@@ -226,7 +226,9 @@ public ElementQuery<T> onPage() {
     }
 
     /**
-     * Return the context (element or driver) to search inside.
+     * Returns the context (element or driver) to search inside.
+     *
+     * @return a {@link SearchContext} instance
      */
     protected SearchContext getContext() {
         return searchContext;
@@ -311,6 +313,8 @@ public T last() {
     /**
      * Executes the search and returns the requested element.
      *
+     * @param index
+     *            the index of the element to return
      * @return The element of the type specified in the constructor
      * @throws NoSuchElementException
      *             if no element is found

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasElementQuery.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasElementQuery.java
@@ -18,6 +18,8 @@ public interface HasElementQuery extends HasSearchContext {
      * it uses the element as its search context. Otherwise the search context
      * is the driver.
      *
+     * @param <T>
+     *            the type of the queried {@link TestBenchElement}
      * @param clazz
      *            the type of element to find, with the tag name defined using
      *            <code>@Element</code> on the class

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasPropertySettersGetters.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasPropertySettersGetters.java
@@ -60,6 +60,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public String getPropertyString(String... propertyNames);
 
@@ -69,6 +70,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public Boolean getPropertyBoolean(String... propertyNames);
 
@@ -78,6 +80,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public TestBenchElement getPropertyElement(String... propertyNames);
 
@@ -88,6 +91,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public List<TestBenchElement> getPropertyElements(String... propertyNames);
 
@@ -97,6 +101,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public Double getPropertyDouble(String... propertyNames);
 
@@ -106,6 +111,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public Integer getPropertyInteger(String... propertyNames);
 
@@ -117,6 +123,7 @@ public interface HasPropertySettersGetters extends WebElement {
      * @param propertyNames
      *            the name of on or more properties, forming a property chain of
      *            type <code>property1.property2.property3</code>
+     * @return the value of the property
      */
     public Object getProperty(String... propertyNames);
 

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasTestBenchCommandExecutor.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/HasTestBenchCommandExecutor.java
@@ -23,7 +23,7 @@ public interface HasTestBenchCommandExecutor {
      * Return a reference to the related {@link TestBenchCommandExecutor}
      * instance.
      *
-     * @return
+     * @return the {@link TestBenchCommandExecutor} instance
      */
     public TestBenchCommandExecutor getCommandExecutor();
 

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/Parameters.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/Parameters.java
@@ -71,6 +71,8 @@ public class Parameters {
      * Turns debugging info on/off
      *
      * @param isDebug
+     *            {@code true} if debugging info should be turned on,
+     *            {@code false} otherwise
      */
     public static void setDebug(boolean isDebug) {
         Parameters.isDebug = isDebug;
@@ -146,7 +148,8 @@ private static String getQualifiedParameter(String unqualifiedName) {
     }
 
     /**
-     * @return true if debugging info is to be shown
+     * @return {@code true} if debugging info should be shown, {@code false}
+     *         otherwise
      */
     public static boolean isDebug() {
         return isDebug;
@@ -158,7 +161,7 @@ public static boolean isDebug() {
      * cursor.
      *
      * @param isScreenshotComparisonCursorDetection
-     *
+     *            {@code true} to enable cursor detection
      */
     public static void setScreenshotComparisonCursorDetection(
             boolean isScreenshotComparisonCursorDetection) {
@@ -169,7 +172,7 @@ public static void setScreenshotComparisonCursorDetection(
      * Tells whether to treat screen shots with the only difference being a text
      * input cursor as equal or not. If true, they will be treated as equal.
      *
-     * @return true if cursor detection is used
+     * @return {@code true} if cursor detection is used, {@code false} otherwise
      */
     public static boolean isScreenshotComparisonCursorDetection() {
         return isScreenshotComparisonCursorDetection;
@@ -179,6 +182,7 @@ public static boolean isScreenshotComparisonCursorDetection() {
      * Sets the directory to search for reference images.
      *
      * @param screenshotReferenceDirectory
+     *            the directory to search for reference images
      */
     public static void setScreenshotReferenceDirectory(
             String screenshotReferenceDirectory) {
@@ -196,6 +200,7 @@ public static String getScreenshotReferenceDirectory() {
      * Sets the directory where error screen shots are stored.
      *
      * @param screenshotErrorDirectory
+     *            the directory path
      */
     public static void setScreenshotErrorDirectory(
             String screenshotErrorDirectory) {
@@ -235,6 +240,7 @@ public static double getScreenshotComparisonTolerance() {
      * the elements to settle into place.
      *
      * @param maxRetries
+     *            the maximum number of retries for screenshot comparisons
      */
     public static void setMaxScreenshotRetries(int maxRetries) {
         maxScreenshotRetries = maxRetries;

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBench.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBench.java
@@ -141,6 +141,8 @@ public static TestBenchElement createElement(WebElement webElement,
      * TestBenchCommandExecutor. This feature is advanced and potentially
      * dangerous.
      *
+     * @param <T>
+     *            the type of the {@link TestBenchElement} to return
      * @param clazz
      *            Class of wanted Element
      * @param webElement

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchDriverProxy.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchDriverProxy.java
@@ -147,6 +147,8 @@ public WebDriver getWrappedDriver() {
      * @param tbCommandExecutor
      *            the {@link TestBenchCommandExecutor} related to the driver
      *            instance
+     * @return a new object containing the wrapped elements and other possible
+     *         values
      */
     protected static Object wrapElementOrElements(
             Object elementElementsOrValues,

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchElement.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchElement.java
@@ -497,6 +497,9 @@ private void autoScrollIntoView() {
      * Use e.g. as
      * <code>waitUntil(ExpectedConditions.presenceOfElementLocated(by), 10);</code>
      *
+     * @param <T>
+     *            The return type of the {@link ExpectedCondition} and this
+     *            method
      * @param condition
      *            Models a condition that might reasonably be expected to
      *            eventually evaluate to something that is neither null nor
@@ -525,6 +528,9 @@ protected <T> T waitUntil(ExpectedCondition<T> condition,
      * Use e.g. as
      * <code>waitUntil(ExpectedConditions.presenceOfElementLocated(by));</code>
      *
+     * @param <T>
+     *            The return type of the {@link ExpectedCondition} and this
+     *            method
      * @param condition
      *            Models a condition that might reasonably be expected to
      *            eventually evaluate to something that is neither null nor

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchTestCase.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/TestBenchTestCase.java
@@ -158,6 +158,8 @@ public List<WebElement> findElements(org.openqa.selenium.By by) {
      * to use component-specific API on elements found using standard Selenium
      * API.
      *
+     * @param <T>
+     *            the type of the {@link TestBenchElement} to return
      * @param elementType
      *            The type (class) containing the API to decorate with
      * @param element
@@ -202,6 +204,9 @@ protected Object executeScript(String script, Object... args) {
      * Use e.g. as
      * <code>waitUntil(ExpectedConditions.presenceOfElementLocated(by), 10);</code>
      *
+     * @param <T>
+     *            The return type of the {@link ExpectedCondition} and this
+     *            method
      * @param condition
      *            Models a condition that might reasonably be expected to
      *            eventually evaluate to something that is neither null nor
@@ -230,6 +235,9 @@ protected <T> T waitUntil(ExpectedCondition<T> condition,
      * Use e.g. as
      * <code>waitUntil(ExpectedConditions.presenceOfElementLocated(by));</code>
      *
+     * @param <T>
+     *            The return type of the {@link ExpectedCondition} and this
+     *            method
      * @param condition
      *            Models a condition that might reasonably be expected to
      *            eventually evaluate to something that is neither null nor

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/ScreenshotComparator.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/ScreenshotComparator.java
@@ -126,8 +126,9 @@ private static BufferedImage getScreenshot(TakesScreenshot driver,
      *            the element to retain in the screenshot
      * @param fullScreen
      *            the full screen image
-     * @return
+     * @return the cropped image
      * @throws IOException
+     *             if element outside of the screenshot
      */
     public static BufferedImage cropToElement(WebElement element,
             BufferedImage fullScreen) throws IOException {

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/TestBenchCommands.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/commands/TestBenchCommands.java
@@ -121,6 +121,7 @@ public interface TestBenchCommands extends CanCompareScreenshots {
      * browser window before interacting with them
      *
      * @param autoScrollIntoView
+     *            {@code true} if elements should be scrolled
      */
     void setAutoScrollIntoView(boolean autoScrollIntoView);
 

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/BrowserUtil.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/BrowserUtil.java
@@ -123,6 +123,7 @@ public static boolean isFirefox(Capabilities capabilities) {
      * naming and screenshots
      *
      * @param capabilities
+     *            to obtain the browser identifier from
      * @return a human readable string describing the capabilities
      */
     public static String getBrowserIdentifier(Capabilities capabilities) {
@@ -146,6 +147,7 @@ public static String getBrowserIdentifier(Capabilities capabilities) {
      * given capabilities. Used mainly for screenshots
      *
      * @param capabilities
+     *            to obtain the platform from
      * @return a human readable string describing the platform
      */
     public static String getPlatform(Capabilities capabilities) {

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/ParallelTest.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/ParallelTest.java
@@ -157,8 +157,10 @@ public void setup() throws Exception {
     }
 
     /**
-     * @return Value of the {@link RunOnHub} annotation of current Class, or
-     *         null if annotation is not present.
+     * @param klass
+     *            the test class to get the {@link RunOnHub} annotation from
+     * @return Value of the {@link RunOnHub} annotation of passed Class, or null
+     *         if annotation is not present.
      */
     protected RunOnHub getRunOnHub(Class<?> klass) {
         if (klass == null) {
@@ -185,7 +187,6 @@ protected String getRunLocallyBrowserVersion() {
     }
 
     /**
-     *
      * @return default capabilities, used if no {@link BrowserConfiguration}
      *         method was found
      */
@@ -198,6 +199,7 @@ public static List<DesiredCapabilities> getDefaultCapabilities() {
      * version)
      *
      * @param desiredCapabilities
+     *            to be set
      */
     public void setDesiredCapabilities(
             DesiredCapabilities desiredCapabilities) {
@@ -219,7 +221,7 @@ List<DesiredCapabilities> getBrowserConfigurationFromParameterOrDefault() {
     /**
      * Gets the {@link DesiredCapabilities} (usually browser name and version)
      *
-     * @return
+     * @return the {@link DesiredCapabilities}
      */
     protected DesiredCapabilities getDesiredCapabilities() {
         return driverConfiguration.getDesiredCapabilities();

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/LocalDriver.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/LocalDriver.java
@@ -36,6 +36,8 @@ public class LocalDriver {
     /**
      * Creates a {@link WebDriver} instance used for running the test locally
      * for debug purposes. Uses firefoxDriver as WebDriver.
+     *
+     * @return a driver instance
      */
     static public WebDriver createDriver() {
         return createDriver(ParallelTest.getDefaultCapabilities().get(0));
@@ -44,6 +46,10 @@ static public WebDriver createDriver() {
     /**
      * Creates a {@link WebDriver} instance used for running the test locally
      * for debug purposes.
+     *
+     * @param desiredCapabilities
+     *            the capabilities to use for the driver
+     * @return a driver instance
      */
     static public WebDriver createDriver(
             DesiredCapabilities desiredCapabilities) {

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/RemoteDriver.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/RemoteDriver.java
@@ -31,10 +31,13 @@ public class RemoteDriver {
     /**
      * Creates a {@link WebDriver} instance used for running the test remotely.
      *
-     * @since
+     * @param hubURL
+     *            the URL of the hub
      * @param capabilities
      *            the type of browser needed
+     * @return a driver instance
      * @throws Exception
+     *             if the driver could not be created
      */
     public WebDriver createDriver(String hubURL,
             DesiredCapabilities capabilities) throws Exception {

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/SetupDriver.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/parallel/setup/SetupDriver.java
@@ -144,6 +144,7 @@ public DesiredCapabilities getDesiredCapabilities() {
      * version)
      *
      * @param desiredCapabilities
+     *            to be set
      */
     public void setDesiredCapabilities(
             DesiredCapabilities desiredCapabilities) {

diff --git a/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageComparison.java b/vaadin-testbench-core/src/main/java/com/vaadin/testbench/screenshot/ImageComparison.java
@@ -90,8 +90,10 @@ private static class ComparisonParameters {
      *            0.025 == 2.5%)
      * @param capabilities
      *            browser capabilities
-     * @return true if images are the same
+     * @return {@code true} if images are the same
      * @throws IOException
+     *             if the reference image cannot be read or error screenshot
+     *             cannot be written
      */
     public boolean imageEqualToReference(BufferedImage screenshotImage,
             String referenceFileId, double errorTolerance,