From f8eb9fdda414d0c98186b98be1fab0350975d7f4 Mon Sep 17 00:00:00 2001 From: Mykola Mokhnach Date: Thu, 28 May 2020 22:15:33 +0200 Subject: [PATCH 1/2] docs: Address warnings printed by docs linter --- src/main/java/io/appium/java_client/ComparesImages.java | 6 ++++++ .../java/io/appium/java_client/battery/BatteryInfo.java | 1 + .../java_client/imagecomparison/ComparisonResult.java | 3 ++- .../io/appium/java_client/internal/CapabilityHelpers.java | 1 + src/main/java/io/appium/java_client/internal/Config.java | 2 ++ .../appium/java_client/pagefactory/utils/ProxyFactory.java | 1 + .../appium/java_client/remote/NewAppiumSessionPayload.java | 5 +++++ .../java_client/screenrecording/CanRecordScreen.java | 7 +++++++ src/main/java/org/openqa/selenium/SearchContext.java | 6 ++++-- 9 files changed, 29 insertions(+), 3 deletions(-) diff --git a/src/main/java/io/appium/java_client/ComparesImages.java b/src/main/java/io/appium/java_client/ComparesImages.java index 060920bb1..3cb85036c 100644 --- a/src/main/java/io/appium/java_client/ComparesImages.java +++ b/src/main/java/io/appium/java_client/ComparesImages.java @@ -74,6 +74,7 @@ default FeaturesMatchingResult matchImagesFeatures(byte[] base64image1, byte[] b * @param image1 The location of the first image * @param image2 The location of the second image * @return The matching result. + * @throws IOException On file system I/O error. */ default FeaturesMatchingResult matchImagesFeatures(File image1, File image2) throws IOException { return matchImagesFeatures(image1, image2, null); @@ -88,6 +89,7 @@ default FeaturesMatchingResult matchImagesFeatures(File image1, File image2) thr * @param image2 The location of the second image * @param options comparison options * @return The matching result. The configuration of fields in the result depends on comparison options. + * @throws IOException On file system I/O error. */ default FeaturesMatchingResult matchImagesFeatures(File image1, File image2, @Nullable FeaturesMatchingOptions options) throws IOException { @@ -137,6 +139,7 @@ default OccurrenceMatchingResult findImageOccurrence(byte[] fullImage, byte[] pa * @param fullImage The location of the full image * @param partialImage The location of the partial image * @return The matching result. The configuration of fields in the result depends on comparison options. + * @throws IOException On file system I/O error. */ default OccurrenceMatchingResult findImageOccurrence(File fullImage, File partialImage) throws IOException { return findImageOccurrence(fullImage, partialImage, null); @@ -152,6 +155,7 @@ default OccurrenceMatchingResult findImageOccurrence(File fullImage, File partia * @param partialImage The location of the partial image * @param options comparison options * @return The matching result. The configuration of fields in the result depends on comparison options. + * @throws IOException On file system I/O error. */ default OccurrenceMatchingResult findImageOccurrence(File fullImage, File partialImage, @Nullable OccurrenceMatchingOptions options) @@ -202,6 +206,7 @@ default SimilarityMatchingResult getImagesSimilarity(byte[] base64image1, byte[] * @param image1 The location of the full image * @param image2 The location of the partial image * @return Matching result. The configuration of fields in the result depends on comparison options. + * @throws IOException On file system I/O error. */ default SimilarityMatchingResult getImagesSimilarity(File image1, File image2) throws IOException { return getImagesSimilarity(image1, image2, null); @@ -217,6 +222,7 @@ default SimilarityMatchingResult getImagesSimilarity(File image1, File image2) t * @param image2 The location of the partial image * @param options comparison options * @return Matching result. The configuration of fields in the result depends on comparison options. + * @throws IOException On file system I/O error. */ default SimilarityMatchingResult getImagesSimilarity(File image1, File image2, @Nullable SimilarityMatchingOptions options) diff --git a/src/main/java/io/appium/java_client/battery/BatteryInfo.java b/src/main/java/io/appium/java_client/battery/BatteryInfo.java index 1ce4ba060..1781db8a5 100644 --- a/src/main/java/io/appium/java_client/battery/BatteryInfo.java +++ b/src/main/java/io/appium/java_client/battery/BatteryInfo.java @@ -25,6 +25,7 @@ public double getLevel() { /** * Returns battery state. * + * @param The type of state data object for the corresponding platform. * @return Battery state value. */ public abstract T getState(); diff --git a/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java b/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java index bd0cad7c5..150ee837c 100644 --- a/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java +++ b/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java @@ -63,10 +63,11 @@ public byte[] getVisualization() { return ((String) getCommandResult().get(VISUALIZATION)).getBytes(StandardCharsets.UTF_8); } - /** + /**javadoc * Stores visualization image into the given file. * * @param destination file to save image. + * @throws IOException On file system I/O error. */ public void storeVisualization(File destination) throws IOException { final byte[] data = Base64.decodeBase64(getVisualization()); diff --git a/src/main/java/io/appium/java_client/internal/CapabilityHelpers.java b/src/main/java/io/appium/java_client/internal/CapabilityHelpers.java index 0cb9ec96c..8688eef13 100644 --- a/src/main/java/io/appium/java_client/internal/CapabilityHelpers.java +++ b/src/main/java/io/appium/java_client/internal/CapabilityHelpers.java @@ -29,6 +29,7 @@ public class CapabilityHelpers { * Helper that is used for capability values retrieval. * Supports both prefixed W3C and "classic" capability names. * + * @param The corresponding capability type. * @param caps driver caps object * @param name capability name * @param expectedType the expected capability type diff --git a/src/main/java/io/appium/java_client/internal/Config.java b/src/main/java/io/appium/java_client/internal/Config.java index 0d0e3febd..fd9ef73c1 100644 --- a/src/main/java/io/appium/java_client/internal/Config.java +++ b/src/main/java/io/appium/java_client/internal/Config.java @@ -33,6 +33,7 @@ private Config(String configName) { /** * Retrieve a value from properties file. * + * @param the value type. * @param key the name of the corresponding key which value to retrieve * @param valueType the expected type of the value to be retrieved * @return the actual value @@ -49,6 +50,7 @@ public T getValue(String key, Class valueType) { /** * Retrieve a value from properties file. * + * @param the type of the resulting value. * @param key the name of the corresponding key which value to retrieve * @param valueType the expected type of the value to be retrieved * @return the actual value or {@link Optional#empty()} if the key is not present diff --git a/src/main/java/io/appium/java_client/pagefactory/utils/ProxyFactory.java b/src/main/java/io/appium/java_client/pagefactory/utils/ProxyFactory.java index 2941e9408..390ebcd92 100644 --- a/src/main/java/io/appium/java_client/pagefactory/utils/ProxyFactory.java +++ b/src/main/java/io/appium/java_client/pagefactory/utils/ProxyFactory.java @@ -36,6 +36,7 @@ public static T getEnhancedProxy(Class requiredClazz, MethodInterceptor i /** * It returns some proxies created by CGLIB. * + * @param The proxy object class. * @param requiredClazz is a {@link java.lang.Class} whose instance should be created * @param params is an array of @link java.lang.Class}. It should be convenient to * parameter types of some declared constructor which belongs to desired diff --git a/src/main/java/io/appium/java_client/remote/NewAppiumSessionPayload.java b/src/main/java/io/appium/java_client/remote/NewAppiumSessionPayload.java index add478a87..8d51f914d 100644 --- a/src/main/java/io/appium/java_client/remote/NewAppiumSessionPayload.java +++ b/src/main/java/io/appium/java_client/remote/NewAppiumSessionPayload.java @@ -120,6 +120,7 @@ private static List getAppiumCapabilities(Class capabilityList) { * * @param caps capabilities to create a new session * @return instance of {@link NewAppiumSessionPayload} + * @throws IOException On file system I/O error. */ public static NewAppiumSessionPayload create(Capabilities caps) throws IOException { boolean forceMobileJSONWP = @@ -235,6 +236,7 @@ private void validate() throws IOException { * Writes json capabilities to some appendable object. * * @param appendable to write a json + * @throws IOException On file system I/O error. */ public void writeTo(Appendable appendable) throws IOException { try (JsonOutput json = new Json().newOutput(appendable)) { @@ -304,6 +306,9 @@ private void writeMetaData(JsonOutput out) throws IOException { * in the W3C WebDriver spec. The OSS {@link Capabilities} are listed first because converting the * OSS capabilities to the equivalent W3C capabilities isn't particularly easy, so it's hoped that * this approach gives us the most compatible implementation. + * + * @return The capabilities as a stream. + * @throws IOException On file system I/O error. */ public Stream stream() throws IOException { // OSS first diff --git a/src/main/java/io/appium/java_client/screenrecording/CanRecordScreen.java b/src/main/java/io/appium/java_client/screenrecording/CanRecordScreen.java index 551a68bec..cea74c04c 100644 --- a/src/main/java/io/appium/java_client/screenrecording/CanRecordScreen.java +++ b/src/main/java/io/appium/java_client/screenrecording/CanRecordScreen.java @@ -29,15 +29,20 @@ public interface CanRecordScreen extends ExecutesMethod { /** * Start asynchronous screen recording process. * + * @param The platform-specific {@link BaseStartScreenRecordingOptions} * @param options see the documentation on the {@link BaseStartScreenRecordingOptions} * descendant for the particular platform. + * @return `not used`. */ + @SuppressWarnings("rawtypes") default String startRecordingScreen(T options) { return CommandExecutionHelper.execute(this, startRecordingScreenCommand(options)); } /** * Start asynchronous screen recording process with default options. + * + * @return `not used`. */ default String startRecordingScreen() { return this.execute(START_RECORDING_SCREEN).getValue().toString(); @@ -46,11 +51,13 @@ default String startRecordingScreen() { /** * Gather the output from the previously started screen recording to a media file. * + * @param The platform-specific {@link BaseStopScreenRecordingOptions} * @param options see the documentation on the {@link BaseStopScreenRecordingOptions} * descendant for the particular platform. * @return Base-64 encoded content of the recorded media file or an empty string * if the file has been successfully uploaded to a remote location (depends on the actual options). */ + @SuppressWarnings("rawtypes") default String stopRecordingScreen(T options) { return CommandExecutionHelper.execute(this, stopRecordingScreenCommand(options)); } diff --git a/src/main/java/org/openqa/selenium/SearchContext.java b/src/main/java/org/openqa/selenium/SearchContext.java index 79501d6d8..d6498972e 100644 --- a/src/main/java/org/openqa/selenium/SearchContext.java +++ b/src/main/java/org/openqa/selenium/SearchContext.java @@ -23,19 +23,21 @@ public interface SearchContext { /** * Find all elements within the current context using the given mechanism. * + * @param The type of the resulting elements. * @param by The locating mechanism to use * @return A list of all {@link WebElement}s, or an empty list if nothing matches * @see org.openqa.selenium.By */ - List findElements(By by); + List findElements(By by); /** * Find the first {@link WebElement} using the given method. * + * @param The type of the resulting element. * @param by The locating mechanism * @return The first matching element on the current context * @throws NoSuchElementException If no matching elements are found */ - T findElement(By by); + T findElement(By by); } From f4a698eae17a331d000648e1dbdea68c724458b2 Mon Sep 17 00:00:00 2001 From: Mykola Mokhnach Date: Thu, 28 May 2020 22:17:02 +0200 Subject: [PATCH 2/2] Fix typo --- .../io/appium/java_client/imagecomparison/ComparisonResult.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java b/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java index 150ee837c..1dcfa3e68 100644 --- a/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java +++ b/src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java @@ -63,7 +63,7 @@ public byte[] getVisualization() { return ((String) getCommandResult().get(VISUALIZATION)).getBytes(StandardCharsets.UTF_8); } - /**javadoc + /** * Stores visualization image into the given file. * * @param destination file to save image.