docs: Address warnings printed by docs linter (#1355)

Author: mykola-mokhnach

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)

src/main/java/io/appium/java_client/battery/BatteryInfo.java

@@ -25,6 +25,7 @@ public double getLevel() {
     /**
      * Returns battery state.
      *
+     * @param <T> The type of state data object for the corresponding platform.
      * @return Battery state value.
      */
     public abstract <T> T getState();

src/main/java/io/appium/java_client/imagecomparison/ComparisonResult.java

@@ -67,6 +67,7 @@ public byte[] getVisualization() {
      * 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());

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 <T>          The corresponding capability type.
      * @param caps         driver caps object
      * @param name         capability name
      * @param expectedType the expected capability type

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 <T> 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> T getValue(String key, Class<T> valueType) {
     /**
      * Retrieve a value from properties file.
      *
+     * @param <T> 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

src/main/java/io/appium/java_client/pagefactory/utils/ProxyFactory.java

@@ -36,6 +36,7 @@ public static <T> T getEnhancedProxy(Class<T> requiredClazz, MethodInterceptor i
     /**
      * It returns some proxies created by CGLIB.
      *
+     * @param <T> 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

src/main/java/io/appium/java_client/remote/NewAppiumSessionPayload.java

@@ -120,6 +120,7 @@ private static List<String> 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<Capabilities> stream() throws IOException {
         // OSS first

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 <T> 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 <T extends BaseStartScreenRecordingOptions> 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 <T> 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 <T extends BaseStopScreenRecordingOptions> String stopRecordingScreen(T options) {
         return CommandExecutionHelper.execute(this, stopRecordingScreenCommand(options));
     }

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 <T> 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
      */
-    <T extends WebElement> List<T>  findElements(By by);
+    <T extends WebElement> List<T> findElements(By by);
 
 
     /**
      * Find the first {@link WebElement} using the given method.
      *
+     * @param <T> 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 extends WebElement> T  findElement(By by);
+    <T extends WebElement> T findElement(By by);
 }