[rb] fix rubydoc warnings

rake-tasks/crazy_fun/mappings/ruby.rb

@@ -131,7 +131,8 @@ def handle(_fun, dir, args)
              :files   => files,
              :gemfile => "build/rb/Gemfile"
 
-        sh "find build/docs/api/rb -type f -name '*.html' -exec sed -i '' 's/build\\/rb\\/lib/lib/g' {} +"
+        # Need a cross-platform solution, perform manually
+        # sh "find build/docs/api/rb -type f -name '*.html' -exec sed -i '' 's/build\\/rb\\/ib/lib/g' {} +"
       end
 
       add_dependencies t, dir, args[:deps]

rb/lib/selenium/webdriver.rb

@@ -50,15 +50,20 @@ def self.root
     #
     # Create a new Driver instance with the correct bridge for the given browser
     #
-    # @param browser [:ie, :internet_explorer, :edge, :remote, :chrome, :firefox, :ff, :phantomjs, :safari]
-    #   the driver type to use
-    # @param *rest
-    #   arguments passed to Bridge.new
+    # @overload for(browser)
+    #   @param [:ie, :internet_explorer, :edge, :remote, :chrome, :firefox, :ff, :phantomjs, :safari] browser The browser to
+    #     create the driver for
+    # @overload for(browser, opts)
+    #   @param [:ie, :internet_explorer, :edge, :remote, :chrome, :firefox, :ff, :phantomjs, :safari] browser The browser to
+    #     create the driver for
+    #   @param [Hash] opts Options passed to Bridge.new
     #
     # @return [Driver]
     #
     # @see Selenium::WebDriver::Remote::Bridge
+    # @see Selenium::WebDriver::Remote::W3CBridge
     # @see Selenium::WebDriver::Firefox::Bridge
+    # @see Selenium::WebDriver::Firefox::W3CBridge
     # @see Selenium::WebDriver::IE::Bridge
     # @see Selenium::WebDriver::Edge::Bridge
     # @see Selenium::WebDriver::Chrome::Bridge
@@ -67,9 +72,9 @@ def self.root
     #
     # @example
     #
-    #   WebDriver.for :firefox, :profile => "some-profile"
-    #   WebDriver.for :firefox, :profile => Profile.new
-    #   WebDriver.for :remote,  :url => "http://localhost:4444/wd/hub", :desired_capabilities => caps
+    #   WebDriver.for :firefox, profile: 'some-profile'
+    #   WebDriver.for :firefox, profile: Profile.new
+    #   WebDriver.for :remote,  url: "http://localhost:4444/wd/hub", desired_capabilities: caps
     #
     # One special argument is not passed on to the bridges, :listener.
     # You can pass a listener for this option to get notified of WebDriver events.

rb/lib/selenium/webdriver/common/action_builder.rb

@@ -69,11 +69,13 @@ def initialize(mouse, keyboard)
       #    el = driver.find_element(id: "some_id")
       #    driver.action.key_down(el, :shift).perform
       #
-      # @param [:shift, :alt, :control, :command, :meta] The key to press.
-      # @param [Selenium::WebDriver::Element] element An optional element
+      # @overload key_down(key)
+      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to press
+      # @overload key_down(element, key)
+      #   @param [Element] element An optional element to move to first
+      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to press
       # @raise [ArgumentError] if the given key is not a modifier
-      # @return [ActionBuilder] A self reference.
-      #
+      # @return [ActionBuilder] A self reference
 
       def key_down(*args)
         @actions << [:mouse, :click, [args.shift]] if args.first.is_a? Element
@@ -95,10 +97,13 @@ def key_down(*args)
       #   el = driver.find_element(id: "some_id")
       #   driver.action.key_up(el, :alt).perform
       #
-      # @param [:shift, :alt, :control, :command, :meta] The modifier key to release.
-      # @param [Selenium::WebDriver::Element] element An optional element
-      # @raise [ArgumentError] if the given key is not a modifier key
-      # @return [ActionBuilder] A self reference.
+      # @overload key_up(key)
+      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to release
+      # @overload key_up(element, key)
+      #   @param [Element] element An optional element to move to first
+      #   @param [:shift, :alt, :control, :command, :meta] key The modifier key to release
+      # @raise [ArgumentError] if the given key is not a modifier
+      # @return [ActionBuilder] A self reference
       #
 
       def key_up(*args)
@@ -124,9 +129,12 @@ def key_up(*args)
       #
       #   driver.action.send_keys("help").perform
       #
-      # @param [Selenium::WebDriver::Element] element An optional element
-      # @param [String] keys The keys to be sent.
-      # @return [ActionBuilder] A self reference.
+      # @overload send_keys(keys)
+      #   @param [Array, Symbol, String] keys The key(s) to press and release
+      # @overload send_keys(element, keys)
+      #   @param [Element] element An optional element to move to first
+      #   @param [Array, Symbol, String] keys The key(s) to press and release
+      # @return [ActionBuilder] A self reference
       #
 
       def send_keys(*args)
@@ -147,7 +155,7 @@ def send_keys(*args)
       #    el = driver.find_element(id: "some_id")
       #    driver.action.click_and_hold(el).perform
       #
-      # @param [Selenium::WebDriver::Element] element the element to move to and click.
+      # @param [Element] element the element to move to and click.
       # @return [ActionBuilder] A self reference.
       #
 
@@ -330,8 +338,6 @@ def drag_and_drop(source, target)
       # @param [Selenium::WebDriver::Element] source Element to emulate button down at.
       # @param [Integer] right_by horizontal move offset.
       # @param [Integer] down_by vertical move offset.
-      # @param [Selenium::WebDriver::Element] target Element to move to and release the
-      #   mouse at.
       # @return [ActionBuilder] A self reference.
       #
 

rb/lib/selenium/webdriver/common/driver.rb

@@ -221,7 +221,7 @@ def window_handle
       #
       # @param [String] script
       #   JavaScript source to execute
-      # @param [WebDriver::Element,Integer, Float, Boolean, NilClass, String, Array] *args
+      # @param [WebDriver::Element, Integer, Float, Boolean, NilClass, String, Array] args
       #   Arguments will be available in the given script in the 'arguments' pseudo-array.
       #
       # @return [WebDriver::Element,Integer,Float,Boolean,NilClass,String,Array]
@@ -241,7 +241,7 @@ def execute_script(script, *args)
       #
       # @param [String] script
       #   JavaScript source to execute
-      # @param [WebDriver::Element,Integer, Float, Boolean, NilClass, String, Array] *args
+      # @param [WebDriver::Element,Integer, Float, Boolean, NilClass, String, Array] args
       #   Arguments to the script. May be empty.
       #
       # @return [WebDriver::Element,Integer,Float,Boolean,NilClass,String,Array]
@@ -274,7 +274,7 @@ def execute_async_script(script, *args)
       # Get the first element matching the given selector. If given a
       # String or Symbol, it will be used as the id of the element.
       #
-      # @param  [String,Hash] id or selector
+      # @param  [String,Hash] sel id or selector
       # @return [WebDriver::Element]
       #
       # Examples:

rb/lib/selenium/webdriver/common/driver_extensions/rotatable.rb

@@ -30,7 +30,7 @@ module Rotatable
         #
         # Change the screen orientation
         #
-        # @param [:landscape, :portrait] Orientation
+        # @param [:landscape, :portrait] orientation
         #
         # @api public
         #

rb/lib/selenium/webdriver/common/element.rb

@@ -108,10 +108,8 @@ def tag_name
       #
       # class, readonly
       #
-      # @param [String]
-      #   attribute name
-      # @return [String,nil]
-      #   attribute value
+      # @param [String] name attribute name
+      # @return [String, nil] attribute value
       #
 
       def attribute(name)
@@ -122,10 +120,8 @@ def attribute(name)
       # Get the value of a the given property with the same name of the element. If the value is not
       # set, nil is returned.
       #
-      # @param [String]
-      #   property name
-      # @return [String,nil]
-      #   property value
+      # @param [String] name property name
+      # @return [String, nil] property value
       #
 
       def property(name)
@@ -145,7 +141,7 @@ def text
       #
       # Send keystrokes to this element
       #
-      # @param [String, Symbol, Array]
+      # @param [String, Symbol, Array] args keystrokes to send
       #
       # Examples:
       #

rb/lib/selenium/webdriver/common/interactions/key_actions.rb

@@ -22,8 +22,8 @@ module WebDriver
     module KeyActions
       #
       # Performs a key press. Does not release the key - subsequent interactions may assume it's kept pressed.
-      # Note that the modifier key is never released implicitly - either #key_up(key) or #release_actions must be
-      # called to release the key.
+      # Note that the key is never released implicitly - either W3CActionBuilder#key_up(key) or W3CActionBuilder#release_actions
+      # must be called to release the key.
       #
       # @example Press a key
       #
@@ -34,19 +34,23 @@ module KeyActions
       #    el = driver.find_element(id: "some_id")
       #    driver.action.key_down(el, :shift).perform
       #
-      # @param [Selenium::WebDriver::Element] element An optional element
-      # @param [:shift, :alt, :control, :command, :meta, 'a'] key The key to press.
-      # @param [Symbol || String] device optional name of the KeyInput device to press the key on
-      # @return [W3CActionBuilder] A self reference.
+      # @overload key_down(key, device: nil)
+      #   @param [Symbol, String] key The key to press
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press the key on
+      # @overload key_down(element, key, device: nil)
+      #   @param [Element] element An optional element to move to first
+      #   @param [Symbol, String] key The key to press
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press the key on
+      # @return [W3CActionBuilder] A self reference
       #
 
       def key_down(*args, device: nil)
         key_action(*args, action: :create_key_down, device: device)
       end
 
       #
-      # Performs a modifier key release.
-      # Releasing a non-depressed modifier key will yield undefined behaviour.
+      # Performs a key release.
+      # Releasing a non-depressed key will yield undefined behaviour.
       #
       # @example Release a key
       #
@@ -57,10 +61,14 @@ def key_down(*args, device: nil)
       #   el = driver.find_element(id: "some_id")
       #   driver.action.key_up(el, :alt).perform
       #
-      # @param [Selenium::WebDriver::Element] element An optional element
-      # @param [:shift, :alt, :control, :command, :meta, 'a'] key The modifier key to release.
-      # @param [Symbol || String] device optional name of the KeyInput device to release the key on
-      # @return [W3CActionBuilder] A self reference.
+      # @overload key_up(key, device: nil)
+      #   @param [Symbol, String] key The key to press
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press the key on
+      # @overload key_up(element, key, device: nil)
+      #   @param [Element] element An optional element to move to first
+      #   @param [Symbol, String] key The key to release
+      #   @param [Symbol, String] device Optional name of the KeyInput device to release the key on
+      # @return [W3CActionBuilder] A self reference
       #
 
       def key_up(*args, device: nil)
@@ -83,10 +91,14 @@ def key_up(*args, device: nil)
       #
       #   driver.action.send_keys("help").perform
       #
-      # @param [Selenium::WebDriver::Element] element An optional element
-      # @param [String] keys The keys to be sent.
-      # @param [Symbol || String] device optional name of the KeyInput device to send keys with
-      # @return [W3CActionBuilder] A self reference.
+      # @overload send_keys(keys, device: nil)
+      #   @param [Array, Symbol, String] keys The key(s) to press and release
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press and release the keys on
+      # @overload send_keys(element, keys, device: nil)
+      #   @param [Element] element An optional element to move to first
+      #   @param [Array, Symbol, String] keys The key(s) to press and release
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press and release the keys on
+      # @return [W3CActionBuilder] A self reference
       #
 
       def send_keys(*args, device: nil)
@@ -100,6 +112,27 @@ def send_keys(*args, device: nil)
 
       private
 
+      #
+      # @api private
+      #
+      # @overload key_down(key, action: nil, device: nil)
+      #   @param [Symbol, String] key The key to press
+      #   @param [Symbol] action The name of the key action to perform
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press the key on
+      # @overload key_down(element, key, action: nil, device: nil)
+      #   @param [Element] element An optional element to move to first
+      #   @param [Symbol, String] key The key to press
+      #   @param [Symbol] action The name of the key action to perform
+      #   @param [Symbol, String] device Optional name of the KeyInput device to press the key on
+      #
+      # @param [Array] args
+      # @option args [Element] element An optional element to move to first
+      # @option args [Symbol, String] key The key to perform the action with
+      # @param [Symbol] action The name of the key action to perform
+      # @param [Symbol, String] device optional name of the KeyInput device to press the key on
+      # @return [W3CActionBuilder] A self reference
+      #
+
       def key_action(*args, action: nil, device: nil)
         key_input = get_device(device) || key_inputs.first
         click(args.shift) if args.first.is_a? Element

rb/lib/selenium/webdriver/common/search_context.rb

@@ -35,20 +35,23 @@ module SearchContext
       }.freeze
 
       #
-      # Find the first element matching the given arguments.
+      # Find the first element matching the given arguments
       #
       # When using Element#find_element with :xpath, be aware that webdriver
       # follows standard conventions: a search prefixed with "//" will search
       # the entire document, not just the children of this current node. Use
       # ".//" to limit your search to the children of the receiving Element.
       #
-      # @param [:class, :class_name, :css, :id, :link_text, :link, :partial_link_text, :name, :tag_name, :xpath] how
-      # @param [String] what
+      # @overload find_element(how, what)
+      #   @param [Symbol, String] how The method to find the element by
+      #   @param [String] what The locator to use
+      # @overload find_element(opts)
+      #   @param [Hash] opts Find options
+      #   @option opts [Symbol] :how Key named after the method to find the element by, containing the locator
       # @return [Element]
       #
       # @raise [Error::NoSuchElementError] if the element doesn't exist
       #
-      #
 
       def find_element(*args)
         how, what = extract_args(args)
@@ -67,10 +70,6 @@ def find_element(*args)
       #
       # @see SearchContext#find_element
       #
-      # @param [:class, :class_name, :css, :id, :link_text, :link, :partial_link_text, :name, :tag_name, :xpath] how
-      # @param [String] what
-      # @return [Array<Element>]
-      #
 
       def find_elements(*args)
         how, what = extract_args(args)

rb/lib/selenium/webdriver/remote/bridge.rb

@@ -33,11 +33,7 @@ class Bridge
         attr_reader :capabilities
 
         #
-        # Initializes the bridge with the given server URL.
-        #
-        # @param url         [String] url for the remote server
-        # @param http_client [Object] an HTTP client instance that implements the same protocol as Http::Default
-        # @param desired_capabilities [Capabilities] an instance of Remote::Capabilities describing the capabilities you want
+        # @see W3CBridge#Initialize
         #
 
         def initialize(opts = {})

rb/lib/selenium/webdriver/remote/w3c_bridge.rb

@@ -36,11 +36,12 @@ class W3CBridge
         attr_reader :capabilities
 
         #
-        # Initializes the bridge with the given server URL.
-        #
-        # @param url         [String] url for the remote server
-        # @param http_client [Object] an HTTP client instance that implements the same protocol as Http::Default
-        # @param desired_capabilities [Capabilities] an instance of Remote::Capabilities describing the capabilities you want
+        # Initializes the bridge with the given server URL
+        # @param [Hash] opts options for the driver
+        # @option opts [String] :url url for the remote server
+        # @option opts [Integer] :port port number for the remote server
+        # @option opts [Object] :http_client an HTTP client instance that implements the same protocol as Http::Default
+        # @option opts [Capabilities] :desired_capabilities an instance of Remote::Capabilities describing the capabilities you want
         #
 
         def initialize(opts = {})