Add filters for start_recording_screen, ios, tweak yardoc (#229)

* add video_filters

* tweak yardoc syntax

* use ' instead of ` in example

* update changelog

Author: KazuCocoa

CHANGELOG.md

@@ -5,6 +5,8 @@ Read `release_notes.md` for commit level details.
 ## [Unreleased]
 
 ### Enhancements
+- Add `video_filters` argument for `start_recording_screen` iOS
+    - It is available over Appium 1.15.0
 
 ### Bug fixes
 

lib/appium_lib_core/android/device.rb

@@ -77,7 +77,7 @@ module Device
         #   Same as #network_connection_type in selenium-webdriver.
         #
         #   Returns a key of <code>{:airplane_mode: 1, wifi: 2, data: 4, all: 6, none: 0}</code> in #network_connection_type
-        #   Returns a number of the mode in `#get_network_connection`
+        #   Returns a number of the mode in +#get_network_connection+
         #
         # @example
         #
@@ -129,7 +129,7 @@ module Device
         #   Defaults to 'Done' for iOS(except for XCUITest).
         # @param [Symbol] strategy The symbol of the strategy which closes the keyboard.
         #   XCUITest ignore this argument.
-        #   Default for iOS is `:pressKey`. Default for Android is `:tapOutside`.
+        #   Default for iOS is +:pressKey+. Default for Android is +:tapOutside+.
         #
         # @example
         #
@@ -154,12 +154,12 @@ module Device
         # @option opts [String] :app_activity The target activity [required]
         # @option opts [String] :app_wait_package The package to start before the target package [optional]
         # @option opts [String] :app_wait_activity The activity to start before the target activity [optional]
-        # @option opts [String] :intent_action The intent action to give it when start the target activity (`-a`) [optional]
-        # @option opts [String] :intent_category The intent category to give it when start the target activity (`-c`) [optional]
-        # @option opts [String] :intent_flags The intent flag to give it when start the target activity (`-f`) [optional]
+        # @option opts [String] :intent_action The intent action to give it when start the target activity (+-a+) [optional]
+        # @option opts [String] :intent_category The intent category to give it when start the target activity (+-c+) [optional]
+        # @option opts [String] :intent_flags The intent flag to give it when start the target activity (+-f+) [optional]
         # @option opts [String] :optional_intent_arguments The optional intent action to give it when start the target activity [optional]
         #                                                  You can set arbitrary arguments with space as string.
-        #                                                  e.g. `'--ez your_extra_bool bool --ei your_extra_int 1'`
+        #                                                  e.g. +'--ez your_extra_bool bool --ei your_extra_int 1'+
         # @option opts [bool] :dont_stop_app_on_reset Do not stop the app when the reset is called in Appium create/delete session [optional]
         #
         # @example
@@ -170,7 +170,7 @@ module Device
 
         # @!method set_network_connection(mode)
         # Set the device network connection mode
-        # Same as `#network_connection_type` in selenium-webdriver.
+        # Same as +#network_connection_type+ in selenium-webdriver.
         #
         # @param [String] mode Bit mask that represent the network mode
         # Or the key matched with <code>{:airplane_mode: 1, wifi: 2, data: 4, all: 6, none: 0}</code>
@@ -204,7 +204,7 @@ module Device
         #   Get the resource usage information of the application.
         #   https://github.com/appium/appium-base-driver/blob/be29aec2318316d12b5c3295e924a5ba8f09b0fb/lib/mjsonwp/routes.js#L303
         # @param [String] package_name: Package name
-        # @param [String] data_type: Data type get with `get_performance_data_types`
+        # @param [String] data_type: Data type get with +get_performance_data_types+
         # @param [String] data_read_timeout: Command timeout. Default is 2.
         #
         # @example
@@ -220,13 +220,13 @@ module Device
         #                             An exception will be thrown if the generated media file is too big to
         #                             fit into the available process memory.
         #                             This option only has an effect if there is screen recording process in progress
-        #                             and `forceRestart` parameter is not set to `true`.
+        #                             and +forceRestart+ parameter is not set to +true+.
         # @param [String] user The name of the user for the remote authentication.
         # @param [String] pass The password for the remote authentication.
         # @param [String] method The http multipart upload method name. The 'PUT' one is used by default.
         # @param [Boolean] force_restart Whether to try to catch and upload/return the currently running screen recording
-        #                                 (`false`, the default setting on server) or ignore the result of it
-        #                                 and start a new recording immediately (`true`).
+        #                                 (+false+, the default setting on server) or ignore the result of it
+        #                                 and start a new recording immediately (+true+).
         #
         # @param [String] video_size The format is widthxheight.
         #                            The default value is the device's native display resolution (if supported),
@@ -241,7 +241,7 @@ module Device
         #                            present then the most recent screen recording chunk is going to be returned as the result.
         # @param [String] bit_rate The video bit rate for the video, in megabits per second.
         #                          4 Mbp/s(4000000) is by default for Android API level below 27. 20 Mb/s(20000000) for API level 27 and above.
-        # @param [Boolean] bug_report Set it to `true` in order to display additional information on the video overlay,
+        # @param [Boolean] bug_report Set it to +true+ in order to display additional information on the video overlay,
         #                             such as a timestamp, that is helpful in videos captured to illustrate bugs.
         #                             This option is only supported since API level 27 (Android P).
         #

lib/appium_lib_core/android/uiautomator2/device.rb

@@ -30,7 +30,7 @@ module Device
           #                 Battery level in range [0.0, 1.0], where 1.0 means 100% charge. -1 is returned
           #                 if the actual value cannot be retrieved from the system.
           #                 Battery state. The following symbols are possible
-          #                 `:unknown, :charging, :discharging, :not_charging, :full`
+          #                 +:unknown, :charging, :discharging, :not_charging, :full+
           #
           # @example
           #

lib/appium_lib_core/common/base/bridge.rb

@@ -58,10 +58,10 @@ def self.handshake(**opts)
 
         # Override
         # Creates session handling both OSS and W3C dialects.
-        # Copy from Selenium::WebDriver::Remote::Bridge to keep using `merged_capabilities` for Appium
+        # Copy from Selenium::WebDriver::Remote::Bridge to keep using +merged_capabilities+ for Appium
         #
-        # If `desired_capabilities` has `forceMjsonwp: true` in the capability, this bridge works with mjsonwp protocol.
-        # If `forceMjsonwp: false` or no the capability, it depends on server side whether this bridge works as w3c or mjsonwp.
+        # If +desired_capabilities+ has +forceMjsonwp: true+ in the capability, this bridge works with mjsonwp protocol.
+        # If +forceMjsonwp: false+ or no the capability, it depends on server side whether this bridge works as w3c or mjsonwp.
         #
         # @param [::Selenium::WebDriver::Remote::W3C::Capabilities, Hash] desired_capabilities A capability
         # @return [::Selenium::WebDriver::Remote::Capabilities, ::Selenium::WebDriver::Remote::W3C::Capabilities]
@@ -125,7 +125,7 @@ def create_session(desired_capabilities)
           json_create(oss_status, value)
         end
 
-        # Append `appium:` prefix for Appium following W3C spec
+        # Append +appium:+ prefix for Appium following W3C spec
         # https://www.w3.org/TR/webdriver/#dfn-validate-capabilities
         #
         # @param [::Selenium::WebDriver::Remote::W3C::Capabilities, Hash] capabilities A capability

lib/appium_lib_core/common/base/bridge/w3c.rb

@@ -43,18 +43,18 @@ def sessions
           end
 
           # Perform touch actions for W3C module.
-          # Generate `touch` pointer action here and users can use this via `driver.action`
+          # Generate +touch+ pointer action here and users can use this via +driver.action+
           # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/W3CActionBuilder.html
           # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/PointerActions.html
           # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/KeyActions.html
           #
-          # 'mouse' action is by default in the Ruby client. Appium server force the `mouse` action to `touch` once in
+          # 'mouse' action is by default in the Ruby client. Appium server force the +mouse+ action to +touch+ once in
           # the server side. So we don't consider the case.
           #
           # @example
           #
           #     element = @driver.find_element(:id, "some id")
-          #     @driver.action.click(element).perform # The `click` is a part of `PointerActions`
+          #     @driver.action.click(element).perform # The 'click' is a part of 'PointerActions'
           #
           def action(async = false)
             # Used for default duration of each touch actions
@@ -143,29 +143,29 @@ def convert_to_element(id)
 
           # For Appium
           # override
-          # called in `extend DriverExtensions::HasNetworkConnection`
+          # called in 'extend DriverExtensions::HasNetworkConnection'
           def network_connection
             execute :get_network_connection
           end
 
           # For Appium
           # override
-          # called in `extend DriverExtensions::HasNetworkConnection`
+          # called in 'extend DriverExtensions::HasNetworkConnection'
           def network_connection=(type)
             execute :set_network_connection, {}, { parameters: { type: type } }
           end
 
           # For Appium
           # No implementation for W3C webdriver module
-          # called in `extend DriverExtensions::HasLocation`
+          # called in 'extend DriverExtensions::HasLocation'
           def location
             obj = execute(:get_location) || {}
             ::Selenium::WebDriver::Location.new obj['latitude'], obj['longitude'], obj['altitude']
           end
 
           # For Appium
           # No implementation for W3C webdriver module
-          # called in `extend DriverExtensions::HasLocation`
+          # called in +extend DriverExtensions::HasLocation+
           # It has below code as well. We should consider the same context in Selenium 4 as backward compatibility.
           #
           #     def location=(loc)