Add yard (#296)

* Setup YARDoc. * Added YARD docs to `Ferrum::Browser::VersionInfo` and `Browser#version`. * Add YARD tags for `Ferrum::Browser#initialize`. * Added YARD docs for `Ferrum::Browser#base_url=`. * Added YARD docs for `Ferrum::Page#go_to`. * Added documentation for `Ferrum::Page#back` and `#forward`. * Added documentation for `Ferrum::Page#refresh`. * Added documentation for `Ferrum::Page#stop`. * Added YARD docs for `Ferrum::Page#position`. * Added YARD docs for `Ferrum::Page#position=`. * Added YARD docs to `Ferrum::Frame::DOM#at_css`. * Added YARD docs to `Ferrum::Frame::DOM#css`. * Added YARD docs to `Ferrum::Frame::DOM#at_xpath`. * Added YARD docs to `Ferrum::Frame::DOM#xpath`. * Added YARD docs for `Ferrum::Frame::DOM#current_url`. * Added YARD docs for `Ferrum::Frame::DOM#current_title`. * Added YARD docs for `Ferrum::Frame::DOM#body`. * Added YARD docs to `Ferrum::Page::Screenshot#screenshot`. * Added YARD docs for `Ferrum::Page::Screenshot#pdf`. * Added YARD docs to `Ferrum::Page::Screenshot#mhtml`. * Added documentation to `Ferrum::Browser#reset`. * Added YARD docs to `Ferrum::Page#network`. * Added YARD docs to `Ferrum::Network#traffic`. * Added YARD docs to `Ferrum::Network#request`. * Added YARD docs to `Ferrum::Network#response`. * Added YARD docs for `Ferrum::Network#status`. * Added YARD docs for `Ferrum::Network#wait_for_idle`. * Added YARD docs to `Ferrum::Network#clear`. * Added YARD docs to `Ferrum::Network#intercept`. * Added YARD docs for `Ferrum::Network#authorize`. * Added YARD docs for `Ferrum::Network#emulate_network_conditions`. * Added YARD docs for `Ferrum::Network#offline_mode`. * Add YARD docs to `Ferrum::Page#mouse`. * Added YARD docs to `Ferrum::Mouse#scroll_to`. * Added YARD docs to `Ferrum::Mouse#click`. * Added YARD docs for `Ferrum::Mouse#down`. * Added YARD docs to `Ferrum::Mouse#up`. * Added YARD docs to `Ferrum::Mouse#move`. * Added YARD docs to `Ferrum::Page#keyboard`. * Added YARD docs for `Ferrum::Keyboard#down`. * Added YARD docs for `Ferrum::Keyboard#up`. * Added YARD docs to `Ferrum::Keyboard#type`. * Added YARD docs to `Ferrum::Keyboard#modifiers`. * Added YARD docs to `Ferrum::Page#cookies`. * Added YARD docs to `Ferrum::Cookies::Cookie`. * Added YARD docs to `Ferrum::Cookies#all`. * Added YARD docs to `Ferrum::Cookies#[]`. * Added YARD docs to `Ferrum::Cookies#set`. * Added YARD docs to `Ferrum::Cookies#remove`. * Added YARD docs to `Ferrum::Cookies#clear`. * Added YARD docs for `Ferrum::Page#headers`. * Added YARD docs for `Ferrum::Headers#get`. * Added YARD docs for `Ferrum::Headers#set`. * Added YARD docs for `Ferrum::Headers#clear`. * Added YARD docs to `Ferrum::Headers#add`. * Added YARD docs for `Ferrum::Frame::Runtime#evaluate`. * Added YARD docs for `Ferrum::Frame::Runtime#evaluate_async`. * Added YARD docs for `Ferrum::Frame::Runtime#execute`. * Added YARD docs for `Ferrum::Browser#evaluate_on_new_document`. * Added YARD docs to `Ferrum::Frame::Runtime#add_script_tag`. * Added YARD docs to `Ferrum::Frame::Runtime#add_style_tag`. * Added YARD docs to `Ferrum::Page#bypass_csp`. * Added YARD docs to `Ferrum::Page::Frames#frames`. * Added YARD docs to `Ferrum::Page::Frames#frame_by`. * Added YARD docs to `Ferrum::Page::Frames#main_frame`. * Added YARD docs to `Ferrum::Frame`'s attributes. * Added YARD docs for `Ferrum::Frame#execution_id`. * Added YARD docs to `Ferrum::Frame#url`. * Added YARD docs to `Ferrum::Frame#title`. * Added YARD docs to `Ferrum::Frame#main?`. * Added YARD docs to `Ferrum::Frame#content=`. * Added YARD docs to `Ferrum::Dialog#accept`. * Added YARD docs to `Ferrum::Dialog#dismiss`. * Added an example to `Ferrum::Dialog#accept`. * Added YARD docs to `Ferrum::Page::Animation#playback_rate`. * Added YARD docs to `Ferrum::Page::Animation#playback_rate=`. * Added YARD docs to `Ferrum::Page::Tracing#record`. * Rescue when `yard` cannot be loaded due to using an alternate CI `Gemfile`. * Added YARD tags to `Ferrum::Network::Exchange`. * Added YARD docs to `Ferrum::Network::Request`. * Added YARD docs to `Ferrum::Network::Response`.
rubycdp · Oct 4, 2022 · 13158c0 · 13158c0
1 parent eec1967
commit 13158c0
Show file tree

Hide file tree

Showing 24 changed files with 1,365 additions and 7 deletions.
diff --git a/.document b/.document
@@ -0,0 +1,4 @@
+lib/**/*.rb
+- 
+CHANGELOG.md
+LICENSE
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,7 @@
 .byebug_history
 Gemfile.*
+doc
 pkg
 .idea
 .ruby-version
+.yardoc
diff --git a/.yardopts b/.yardopts
@@ -0,0 +1 @@
+--markup markdown --title 'Ferrum Documentation'
diff --git a/Gemfile b/Gemfile
@@ -7,4 +7,8 @@ gem "rubocop", "~> 1.22"
 gem "rubocop-rake", require: false
 gem "rubocop-rspec", require: false
 
+gem 'kramdown', '~> 2.0', require: false
+gem 'redcarpet', require: false, platform: :mri
+gem 'yard', '~> 0.9', require: false
+
 gemspec
diff --git a/Rakefile b/Rakefile
@@ -9,3 +9,10 @@ RSpec::Core::RakeTask.new("test") do |t|
 end
 
 task default: :test
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+  task docs: :yard
+rescue LoadError
+end
diff --git a/lib/ferrum/browser.rb b/lib/ferrum/browser.rb
@@ -38,6 +38,92 @@ class Browser
                 :proxy_server
     attr_writer :timeout
 
+    #
+    # Initializes the browser.
+    #
+    # @param [Hash{Symbol => Object}, nil] options
+    #   Additional browser options.
+    #
+    # @option options [Boolean] :headless (true)
+    #   Set browser as headless or not.
+    #
+    # @option options [Boolean] :xvfb (false)
+    #   Run browser in a virtual framebuffer.
+    #
+    # @option options [(Integer, Integer)] :window_size ([1024, 768])
+    #   The dimensions of the browser window in which to test, expressed as a
+    #   2-element array, e.g. `[1024, 768]`.
+    #
+    # @option options [Array<String, Hash>] :extensions
+    #   An array of paths to files or JS source code to be preloaded into the
+    #   browser e.g.: `["/path/to/script.js", { source: "window.secret = 'top'" }]`
+    #
+    # @option options [#puts] :logger
+    #   When present, debug output is written to this object.
+    #
+    # @option options [Integer, Float] :slowmo
+    #   Set a delay in seconds to wait before sending command.
+    #   Usefull companion of headless option, so that you have time to see
+    #   changes.
+    #
+    # @option options [Numeric] :timeout (5)
+    #   The number of seconds we'll wait for a response when communicating with
+    #   browser.
+    #
+    # @option options [Boolean] :js_errors
+    #   When true, JavaScript errors get re-raised in Ruby.
+    #
+    # @option options [Boolean] :pending_connection_errors (true)
+    #   When main frame is still waiting for slow responses while timeout is
+    #   reached {PendingConnectionsError} is raised. It's better to figure out
+    #   why you have slow responses and fix or block them rather than turn this
+    #   setting off.
+    #
+    # @option options [:chrome, :firefox] :browser_name (:chrome)
+    #   Sets the browser's name. **Note:** only experimental support for
+    #   `:firefox` for now.
+    #
+    # @option options [String] :browser_path
+    #   Path to Chrome binary, you can also set ENV variable as
+    #   `BROWSER_PATH=some/path/chrome bundle exec rspec`.
+    #
+    # @option options [Hash] :browser_options
+    #   Additional command line options, [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
+    #   e.g. `{ "ignore-certificate-errors" => nil }`
+    #
+    # @option options [Boolean] :ignore_default_browser_options
+    #   Ferrum has a number of default options it passes to the browser,
+    #   if you set this to `true` then only options you put in
+    #   `:browser_options` will be passed to the browser, except required ones
+    #   of course.
+    #
+    # @option options [Integer] :port
+    #   Remote debugging port for headless Chrome.
+    #
+    # @option options [String] :host
+    #   Remote debugging address for headless Chrome.
+    #
+    # @option options [String] :url
+    #   URL for a running instance of Chrome. If this is set, a browser process
+    #   will not be spawned.
+    #
+    # @option options [Integer] :process_timeout
+    #   How long to wait for the Chrome process to respond on startup.
+    #
+    # @option options [Integer] :ws_max_receive_size
+    #   How big messages to accept from Chrome over the web socket, in bytes.
+    #   Defaults to 64MB. Incoming messages larger this will cause a
+    #   {Ferrum::DeadBrowserError}.
+    #
+    # @option options [Hash] :proxy
+    #   Specify proxy settings, [read more](https://github.com/rubycdp/ferrum#proxy).
+    #
+    # @option options [String] :save_path
+    #   Path to save attachments with [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header.
+    #
+    # @option options [Hash] :env
+    #   Environment variables you'd like to pass through to the process.
+    #
     def initialize(options = nil)
       options ||= {}
 
@@ -80,6 +166,15 @@ def initialize(options = nil)
       start
     end
 
+    #
+    # Sets the base URL.
+    #
+    # @param [String] value
+    #   The new base URL value.
+    #
+    # @return [String]
+    #   The base URL value.
+    #
     def base_url=(value)
       parsed = Addressable::URI.parse(value)
       unless BASE_URL_SCHEMA.include?(parsed.normalized_scheme)
@@ -111,6 +206,19 @@ def extensions
       end
     end
 
+    #
+    # Evaluate JavaScript to modify things before a page load.
+    #
+    # @param [String] expression
+    #   The JavaScript to add to each new document.
+    #
+    # @example
+    #   browser.evaluate_on_new_document <<~JS
+    #     Object.defineProperty(navigator, "languages", {
+    #       get: function() { return ["tlh"]; }
+    #     });
+    #   JS
+    #
     def evaluate_on_new_document(expression)
       extensions << expression
     end
@@ -126,6 +234,20 @@ def command(*args)
       raise
     end
 
+    #
+    # Closes browser tabs opened by the `Browser` instance.
+    #
+    # @example
+    #   # connect to a long-running Chrome process
+    #   browser = Ferrum::Browser.new(url: 'http://localhost:9222')
+    #
+    #   browser.go_to("https://github.com/")
+    #
+    #   # clean up, lest the tab stays there hanging forever
+    #   browser.reset
+    #
+    #   browser.quit
+    #
     def reset
       @window_size = @original_window_size
       contexts.reset
@@ -151,6 +273,13 @@ def crash
       command("Browser.crash")
     end
 
+    #
+    # Gets the version information from the browser.
+    #
+    # @return [VersionInfo]
+    #
+    # @since 0.13
+    #
     def version
       VersionInfo.new(command("Browser.getVersion"))
     end

diff --git a/lib/ferrum/browser/version_info.rb b/lib/ferrum/browser/version_info.rb
@@ -1,27 +1,67 @@
 module Ferrum
   class Browser
+    #
+    # The browser's version information returned by [Browser.getVersion].
+    #
+    # [Browser.getVersion]: https://chromedevtools.github.io/devtools-protocol/1-3/Browser/#method-getVersion
+    #
+    # @since 0.13
+    #
     class VersionInfo
 
+      #
+      # Initializes the browser's version information.
+      #
+      # @param [Hash{String => Object}] properties
+      #   The object properties returned by [Browser.getVersion](https://chromedevtools.github.io/devtools-protocol/1-3/Browser/#method-getVersion).
+      #
+      # @api private
+      #
       def initialize(properties)
         @properties = properties
       end
 
+      #
+      # The Chrome DevTools protocol version.
+      #
+      # @return [String]
+      #
       def protocol_version
         @properties['protocolVersion']
       end
 
+      #
+      # The Chrome version.
+      #
+      # @return [String]
+      #
       def product
         @properties['product']
       end
 
+      #
+      # The Chrome revision properties.
+      #
+      # @return [String]
+      #
       def revision
         @properties['revision']
       end
 
+      #
+      # The Chrome `User-Agent` string.
+      #
+      # @return [String]
+      #
       def user_agent
         @properties['userAgent']
       end
 
+      #
+      # The JavaScript engine version.
+      #
+      # @return [String]
+      #
       def js_version
         @properties['jsVersion']
       end
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		--markup markdown --title 'Ferrum Documentation'