fix documentation

use option

lib/appium_lib_core/android/device.rb

@@ -3,6 +3,8 @@ module Android
     module Device
       extend Forwardable
 
+      # rubocop:disable Metrics/LineLength
+
       # @!method hide_keyboard(close_key = nil, strategy = nil)
       # Hide the onscreen keyboard
       # @param [String] close_key The name of the key which closes the keyboard.
@@ -27,10 +29,11 @@ module Device
       # @!method start_activity(opts)
       # Android only. Start a new activity within the current app or launch a new app and start the target activity.
       #
-      # @option [String] The package owning the activity [required]
-      # @option [String] The target activity [required]
-      # @option opts [String] The package to start before the target package [optional]
-      # @option opts [String] The activity to start before the target activity [optional]
+      # @param opts [Hash] Options
+      # @option opts [String] :app_package The package owning the activity [required]
+      # @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]
       #
       # @example
       #
@@ -69,40 +72,38 @@ module Device
       # @!method get_performance_data(package_name:, data_type:, data_read_timeout: 1000)
       #   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_read_timeout Command timeout. Default is 2.
+      # @param [String] package_name: Package name
+      # @param [String] data_type: Data type get with `get_performance_data_types`
+      # @param [String] data_read_timeout: Command timeout. Default is 2.
       #
       # @example
       #
       #   @driver.get_performance_data package_name: package_name, data_type: data_type, data_read_timeout: 2
       #
 
-      # @!method start_recording_screen(remote_path:, user:, pass:, method:, force_restart:,
-      #                                 video_size:, time_limit:, bit_rate:)
-      #
-      # @option [String] remote_path The path to the remote location, where the resulting video should be uploaded.
+      # @!method start_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT', force_restart: nil, video_size: nil, time_limit: '180', bit_rate: '4000000')
+      # @param [String] remote_path: The path to the remote location, where the resulting video should be uploaded.
       #                             The following protocols are supported: http/https, ftp.
       #                             Null or empty string value (the default setting) means the content of resulting
       #                             file should be encoded as Base64 and passed as the endpoint response value.
       #                             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`.
-      # @option [String] user The name of the user for the remote authentication.
-      # @option [String] pass The password for the remote authentication.
-      # @option [String] method The http multipart upload method name. The 'PUT' one is used by default.
-      # @option [Boolean] force_restart Whether to try to catch and upload/return the currently running screen recording
+      # @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`).
       #
-      # @option [String] video_size The format is widthxheight.
+      # @param [String] video_size: The format is widthxheight.
       #                             The default value is the device's native display resolution (if supported),
       #                             1280x720 if not. For best results,
       #                             use a size supported by your device's Advanced Video Coding (AVC) encoder.
       #                             For example, "1280x720"
-      # @param [String] time_limit Recording time. 180 seconds is by default.
-      # @param [String] bit_rate The video bit rate for the video, in megabits per second. 4 Mbps(4000000) is by default.
+      # @param [String] time_limit: Recording time. 180 seconds is by default.
+      # @param [String] bit_rate: The video bit rate for the video, in megabits per second. 4 Mbps(4000000) is by default.
       #
       # @example
       #
@@ -114,6 +115,8 @@ module Device
       ## class << self
       ####
 
+      # rubocop:enable Metrics/LineLength
+
       class << self
         def extended(_mod)
           Appium::Core::Device.extend_webdriver_with_forwardable

lib/appium_lib_core/common/device.rb

@@ -402,17 +402,16 @@ module Device
       #   @driver.take_element_screenshot(element, "fine_name.png")
       #
 
-      # @!method stop_recording_screen(remote_path:, user:, pass:, method:)
-      #
-      # @option [String] remote_path The path to the remote location, where the resulting video should be uploaded.
+      # @!method stop_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT')
+      # @param [String] remote_path: The path to the remote location, where the resulting video should be uploaded.
       #                             The following protocols are supported: http/https, ftp.
       #                             Null or empty string value (the default setting) means the content of resulting
       #                             file should be encoded as Base64 and passed as the endpoint response value.
       #                             An exception will be thrown if the generated media file is too big to
       #                             fit into the available process memory.
-      # @option [String] user The name of the user for the remote authentication.
-      # @option [String] pass The password for the remote authentication.
-      # @option [String] method The http multipart upload method name. The 'PUT' one is used by default.
+      # @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.
       #
       # @example
       #
@@ -421,8 +420,7 @@ module Device
       #
 
       # @!method stop_and_save_recording_screen(file_path)
-      #
-      # @option [String] file_path The path to save video decoded from base64 from Appium server.
+      # @param [String] file_path The path to save video decoded from base64 from Appium server.
       #
       # @example
       #

lib/appium_lib_core/device/touch_actions.rb

@@ -28,6 +28,7 @@ def initialize(driver)
       #
       # `move_to`'s `x` and `y` have two case. One is working as coordinate, the other is working as offset.
       #
+      # @param opts [Hash] Options
       # @option opts [integer] :x x co-ordinate to move to if element isn't set. Works as an offset if x is set with Element.
       # @option opts [integer] :y y co-ordinate to move to if element isn't set. Works as an offset if y is set with Element.
       # @option opts [WebDriver::Element] Element to scope this move within.
@@ -41,19 +42,20 @@ def move_to(opts)
       # https://github.com/appium/ruby_lib/issues/231#issuecomment-269895512
       # e.g. Appium::TouchAction.new.press(x: 280, y: 530).wait(2000).release.perform
       #
-      # @option element [WebDriver::Element] the element to press.
-      # @option x [integer] x co-ordinate to press on.
-      # @option y [integer] y co-ordinate to press on.
-      # @option duration [integer] Number of milliseconds to press.
+      # @param opts [Hash] Options
+      # @option opts [WebDriver::Element] element the element to press.
+      # @option opts [integer] x X co-ordinate to press on.
+      # @option opts [integer] y Y co-ordinate to press on.
+      # @option opts [integer] duration Number of milliseconds to press.
       def long_press(opts)
         args = opts.select { |k, _v| %i(element x y duration).include? k }
         args = args_with_ele_ref(args)
         chain_method(:longPress, args) # longPress is what the appium server expects
       end
 
-      # Press a finger onto the screen.  Finger will stay down until you call
-      # `release`.
+      # Press a finger onto the screen.  Finger will stay down until you call `release`.
       #
+      # @param opts [Hash] Options
       # @option opts [WebDriver::Element] :element (Optional) Element to press within.
       # @option opts [integer] :x x co-ordinate to press on
       # @option opts [integer] :y y co-ordinate to press on
@@ -65,6 +67,7 @@ def press(opts)
 
       # Remove a finger from the screen.
       #
+      # @param opts [Hash] Options
       # @option opts [WebDriver::Element] :element (Optional) Element to release from.
       # @option opts [integer] :x x co-ordinate to release from
       # @option opts [integer] :y y co-ordinate to release from
@@ -76,6 +79,7 @@ def release(opts = nil)
       # Touch a point on the screen.
       # Alternatively, you can use `press(...).release.perform` instead of `tap(...).perform`.
       #
+      # @param opts [Hash] Options
       # @option opts [WebDriver::Element] :element (Optional) Element to restrict scope too.
       # @option opts [integer] :x x co-ordinate to tap
       # @option opts [integer] :y y co-ordinate to tap
@@ -89,6 +93,7 @@ def tap(opts)
 
       # Double tap an element on the screen
       #
+      # @param opts [Hash] Options
       # @option opts [WebDriver::Element] :element (Optional) Element to restrict scope too.
       # @option opts [integer] :x x co-ordinate to tap
       # @option opts [integer] :y y co-ordinate to tap
@@ -101,6 +106,7 @@ def double_tap(opts)
 
       # Two finger tap an element on the screen
       #
+      # @param opts [Hash] Options
       # @option opts [WebDriver::Element] :element (Optional) Element to restrict scope too.
       # @option opts [integer] :x x co-ordinate to tap
       # @option opts [integer] :y y co-ordinate to tap
@@ -128,6 +134,7 @@ def wait(milliseconds)
       # If you'd like more details, please read tests and its log samples in
       # `ios_tests/lib/ios/specs/device/touch_actions.rb` and `ios_tests/lib/ios/specs/device/touch_actions.rb`
       #
+      # @param opts [Hash] Options
       # @option opts [int] :start_x Where to start swiping, on the x axis.  Default 0.
       # @option opts [int] :start_y Where to start swiping, on the y axis.  Default 0.
       # @option opts [int] :offset_x Offset, on the x axis.  Default 0.

lib/appium_lib_core/driver.rb

@@ -19,7 +19,7 @@ class Driver
       attr_reader :automation_name
 
       # Custom URL for the selenium server. If set this attribute, ruby_lib_core try to handshake to the custom url.
-      # False is by default and then "http://127.0.0.1:#{@port}/wd/hub" is used.
+      # False is by default and then "http://127.0.0.1:#{port}/wd/hub" is used.
       # @return [String]
       attr_reader :custom_url
 
@@ -116,6 +116,7 @@ def initialize(target, opts = {})
       # You can customise http_client as the following
       #
       # @param [String] server_url Custom server url to send to requests. Default is "http://127.0.0.1:4723/wd/hub".
+      # @param http_client_ops [Hash] Options for http client
       # @option http_client_ops [Hash] :http_client Custom HTTP Client
       # @option http_client_ops [Hash] :open_timeout Custom open timeout for http client.
       # @option http_client_ops [Hash] :read_timeout Custom read timeout for http client.

lib/appium_lib_core/ios/xcuitest/device.rb

@@ -4,6 +4,8 @@ module Xcuitest
       module Device
         extend Forwardable
 
+        # rubocop:disable Metrics/LineLength
+
         # @!method hide_keyboard(close_key = nil, strategy = nil)
         # Hide the onscreen keyboard
         # @param [String] close_key The name of the key which closes the keyboard.
@@ -29,29 +31,26 @@ module Device
         #   @driver.background_app(-1) #=> the app never come back. https://github.com/appium/appium/issues/7741
         #
 
-        # @!method start_recording_screen(remote_path:, user:, pass:, method:, force_restart:,
-        #                                 video_type:, time_limit:, video_quality:)
-        #
-        # @option [String] remote_path The path to the remote location, where the resulting video should be uploaded.
+        # @!method start_recording_screen(remote_path: nil, user: nil, pass: nil, method: nil, force_restart: nil, video_type: 'mp4', time_limit: '180', video_quality: 'medium')
+        # @param [String] remote_path: The path to the remote location, where the resulting video should be uploaded.
         #                             The following protocols are supported: http/https, ftp.
         #                             Null or empty string value (the default setting) means the content of resulting
         #                             file should be encoded as Base64 and passed as the endpount response value.
         #                             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 progreess
         #                             and `forceRestart` parameter is not set to `true`.
-        # @option [String] user The name of the user for the remote authentication.
-        # @option [String] pass The password for the remote authentication.
-        # @option [String] method The http multipart upload method name. The 'PUT' one is used by default.
-        # @option [Boolean] force_restart Whether to try to catch and upload/return the currently running screen recording
+        # @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`).
-        #
-        # @param [String] video_type The format of the screen capture to be recorded.
+        # @param [String] video_type: The format of the screen capture to be recorded.
         #                            Available formats: "h264", "mp4" or "fmp4". Default is "mp4".
         #                            Only works for Simulator.
-        # @param [String] time_limit Recording time. 180 seconds is by default.
-        # @param [String] video_quality The video encoding quality (low, medium, high, photo - defaults to medium).
+        # @param [String] time_limit: Recording time. 180 seconds is by default.
+        # @param [String] video_quality: The video encoding quality (low, medium, high, photo - defaults to medium).
         #                               Only works for real devices.
         #
         # @example
@@ -60,6 +59,8 @@ module Device
         #    @driver.start_recording_screen video_type: 'h264', time_limit: '260'
         #
 
+        # rubocop:enable Metrics/LineLength
+
         ####
         ## class << self
         ####