Merge pull request #18 from remove-bg/add-yard-docs

Add YARD for detailed docs

Gemfile.lock

@@ -81,6 +81,7 @@ GEM
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.25)
 
 PLATFORMS
   ruby
@@ -100,6 +101,7 @@ DEPENDENCIES
   vcr
   vcr_better_binary
   webmock
+  yard
 
 BUNDLED WITH
    2.1.4

README.md

@@ -51,6 +51,8 @@ The full installation has the following resolution limits:
 
 # Usage
 
+For more in-depth documentation please see [RubyDoc](https://www.rubydoc.info/gems/remove_bg)
+
 ## Configuring an API key
 
 To configure a global API key (used by default unless overridden per request):
@@ -173,11 +175,22 @@ Bug reports and pull requests are welcome on GitHub at [remove-bg/ruby](https://
 
 ## Development
 
+### Setup
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake spec` to run the tests.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
+### Releasing a new version
+To release a new version, update the version number in `version.rb`, and then run
 `bundle exec rake release`, which will create a git tag for the version, push
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
+
+### Documentation
+
+To preview the [YARD documentation](https://yardoc.org/) locally run:
+
+```
+bundle exec yard server --reload
+open http://localhost:8808/
+```

lib/remove_bg.rb

@@ -4,21 +4,38 @@
 require "remove_bg/request_options"
 
 module RemoveBg
+  # Removes the background from an image on the local file system
+  # @param image_path [String] Path to the input image
+  # @param options [Hash<Symbol, Object>] Image processing options (see API docs)
+  # @return [RemoveBg::Result|RemoveBg::CompositeResult] a processed image result
+  #
   def self.from_file(image_path, raw_options = {})
     options = RemoveBg::RequestOptions.new(raw_options)
     ApiClient.new.remove_from_file(image_path, options)
   end
 
+  # Removes the background from the image at the URL specified
+  # @param image_url [String] Absolute URL of the input image
+  # @param options [Hash<Symbol, Object>] Image processing options (see API docs)
+  # @return [RemoveBg::Result|RemoveBg::CompositeResult] A processed image result
+  #
   def self.from_url(image_url, raw_options = {})
     options = RemoveBg::RequestOptions.new(raw_options)
     ApiClient.new.remove_from_url(image_url, options)
   end
 
+  # Fetches account information for the globally configured API key, or a
+  # specific API key if provided
+  # @param options [Hash<Symbol, Object>]
+  # @return [RemoveBg::AccountInfo]
+  #
   def self.account_info(raw_options = {})
     options = RemoveBg::BaseRequestOptions.new(raw_options)
     ApiClient.new.account_info(options)
   end
 
+  # Yields the global Remove.bg configuration
+  # @yield [RemoveBg::Configuration]
   def self.configure
     yield RemoveBg::Configuration.configuration
   end

lib/remove_bg/account_info.rb

@@ -1,6 +1,10 @@
 module RemoveBg
   class AccountInfo
-    attr_reader :api, :credits
+    # @return [RemoveBg::AccountInfo::ApiInfo]
+    attr_reader :api
+
+    # @return [RemoveBg::AccountInfo::CreditsInfo]
+    attr_reader :credits
 
     def initialize(attributes)
       @api = ApiInfo.new(**attributes.fetch(:api))

lib/remove_bg/api_client.rb

@@ -16,21 +16,40 @@ module RemoveBg
   class ApiClient
     include RemoveBg::Api
 
+    # @param connection [Faraday::Connection]
+    #
     def initialize(connection: RemoveBg::HttpConnection.build)
       @connection = connection
     end
 
+    # Removes the background from an image on the local file system
+    # @param image_path [String]
+    # @param options [RemoveBg::RequestOptions]
+    # @return [RemoveBg::Result|RemoveBg::CompositeResult]
+    # @raise [RemoveBg::Error]
+    #
     def remove_from_file(image_path, options)
       data = options.data.merge(image_file: Upload.for_file(image_path))
       request_remove_bg(data, options.api_key)
     end
 
+    # Removes the background from the image at the URL specified
+    # @param image_url [String]
+    # @param options [RemoveBg::RequestOptions]
+    # @return [RemoveBg::Result|RemoveBg::CompositeResult]
+    # @raise [RemoveBg::Error]
+    #
     def remove_from_url(image_url, options)
       RemoveBg::UrlValidator.validate(image_url)
       data = options.data.merge(image_url: image_url)
       request_remove_bg(data, options.api_key)
     end
 
+    # Fetches account information
+    # @param options [RemoveBg::BaseRequestOptions]
+    # @return [RemoveBg::AccountInfo]
+    # @raise [RemoveBg::Error]
+    #
     def account_info(options)
       request_account_info(options.api_key)
     end

lib/remove_bg/composite_result.rb

@@ -1,7 +1,17 @@
 require_relative "result"
 
 module RemoveBg
+  # Handles image composition for larger images (over 10MP) where transparency is
+  # required.
+  # @see RemoveBg::Result
+  #
   class CompositeResult < Result
+    # Saves the ZIP archive containing the alpha.png and color.jpg files
+    # (useful if you want to handle composition yourself)
+    # @param file_path [string]
+    # @param overwrite [boolean] Overwrite any existing file at the specified path
+    # @return [nil]
+    #
     def save_zip(file_path, overwrite: false)
       if File.exist?(file_path) && !overwrite
         raise FileOverwriteError.new(file_path)

lib/remove_bg/error.rb

@@ -2,7 +2,11 @@ module RemoveBg
   class Error < StandardError; end
 
   class HttpError < Error
-    attr_reader :http_response, :http_response_body
+    # @return [Faraday::Response]
+    attr_reader :http_response
+
+    # @return [String]
+    attr_reader :http_response_body
 
     def initialize(message, http_response, http_response_body)
       @http_response = http_response
@@ -11,9 +15,13 @@ def initialize(message, http_response, http_response_body)
     end
   end
 
+  # Raised for all HTTP 4XX errors
   class ClientHttpError < HttpError; end
+
+  # Raised for all HTTP 5XX errors
   class ServerHttpError < HttpError; end
 
+  # Raised for HTTP 429 status code
   class RateLimitError < ClientHttpError
     attr_reader :rate_limit
 

lib/remove_bg/http_connection.rb

@@ -8,6 +8,8 @@ class HttpConnection
     HTTP_BASE_TIMEOUT = 10
     HTTP_WRITE_TIMEOUT = 120
 
+    # @return [Faraday::Connection]
+    #
     def self.build(api_url = RemoveBg::Api::URL)
       retry_options = {
         max: 2,

lib/remove_bg/image_composer.rb

@@ -1,6 +1,11 @@
 require_relative "error"
 
 module RemoveBg
+  # Combines alpha.png and color.jpg files to produce a full-sized transparent PNG.
+  # An image processing library (ImageMagick, GraphicsMagick, or libvips) must
+  # be available on the system.
+  # @see RemoveBg::CompositeResult
+  #
   class ImageComposer
     DEFAULT_BINARY_DETECTOR = lambda do |binary_name|
       system("which", binary_name, out: File::NULL)

lib/remove_bg/request_options.rb

@@ -1,6 +1,8 @@
 require_relative "base_request_options"
 
 module RemoveBg
+  # Options for image processing requests. Arbitary options are passed directly to the API.
+  #
   class RequestOptions < BaseRequestOptions
     SIZE_REGULAR = "regular"
     SIZE_MEDIUM = "medium"

lib/remove_bg/result.rb

@@ -5,10 +5,17 @@
 require_relative "image_composer"
 
 module RemoveBg
+  # Provides convenience methods to save the processed image, read the image data,
+  # and access metadata such as the image height/width and credits charged.
+  #
   class Result
     extend ::Forwardable
 
-    attr_reader :metadata, :rate_limit
+    # @return [RemoveBg::ResultMetadata]
+    attr_reader :metadata
+
+    # @return [RemoveBg::RateLimitInfo]
+    attr_reader :rate_limit
 
     def_delegators :metadata, :type, :width, :height, :credits_charged
 
@@ -18,6 +25,11 @@ def initialize(download:, metadata:, rate_limit:)
       @rate_limit = rate_limit
     end
 
+    # Saves the processed image to the path specified
+    # @param file_path [string]
+    # @param overwrite [boolean] Overwrite any existing file at the specified path
+    # @return [nil]
+    #
     def save(file_path, overwrite: false)
       if File.exist?(file_path) && !overwrite
         raise FileOverwriteError.new(file_path)
@@ -26,6 +38,9 @@ def save(file_path, overwrite: false)
       FileUtils.cp(image_file, file_path)
     end
 
+    # Returns the binary data of the processed image
+    # @return [String]
+    #
     def data
       image_file.rewind
       image_file.read

remove_bg.gemspec

@@ -39,4 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "vcr_better_binary"
   spec.add_development_dependency "vcr"
   spec.add_development_dependency "webmock"
+  spec.add_development_dependency "yard"
 end