Merge branch '1.0' of https://github.com/lostisland/faraday into feat…

…ure/#762-rspec

README.md

@@ -15,15 +15,15 @@ Faraday supports these adapters out of the box:
 
 * [Net::HTTP][net_http] _(default)_
 * [Net::HTTP::Persistent][persistent]
-* [Excon][]
-* [Patron][]
-* [EventMachine][]
-* [HTTPClient][]
+* [Excon][excon]
+* [Patron][patron]
+* [EventMachine][eventmachine]
+* [HTTPClient][httpclient]
 
 Adapters are slowly being moved into their own gems, or bundled with HTTP clients.
 Here is the list of known external adapters:
 
-* [Typhoeus][]
+* [Typhoeus][typhoeus]
 
 It also includes a Rack adapter for hitting loaded Rack applications through
 Rack::Test, and a Test adapter for stubbing requests by hand.
@@ -70,7 +70,7 @@ conn = Faraday.new(:url => 'http://sushi.com/api_key=s3cr3t') do |faraday|
 end
 ```
 
-Once you have the connection object, use it to make HTTP requests. You can pass paramters to it in a few different ways:
+Once you have the connection object, use it to make HTTP requests. You can pass parameters to it in a few different ways:
 
 ```ruby
 ## GET ##

lib/faraday/connection.rb

@@ -39,8 +39,8 @@ class Connection
     # Public: Sets the default parallel manager for this connection.
     attr_writer :default_parallel_manager
 
-    # Public: Gets or Sets the Hash proxy options.
-    # attr_reader :proxy
+    # Public: Gets the Hash proxy options.
+    attr_reader :proxy
 
     # Public: Initializes a new Faraday::Connection.
     #
@@ -275,14 +275,6 @@ def in_parallel(manager = nil)
       @parallel_manager = nil
     end
 
-    # Public: Gets or Sets the Hash proxy options.
-    def proxy(arg = nil)
-      return @proxy if arg.nil?
-      warn 'Warning: use of proxy(new_value) to set connection proxy have been DEPRECATED and will be removed in Faraday 1.0'
-      @manual_proxy = true
-      @proxy = ProxyOptions.from(arg)
-    end
-
     # Public: Sets the Hash proxy options.
     def proxy=(new_value)
       @manual_proxy = true

lib/faraday/error.rb

@@ -1,6 +1,5 @@
 module Faraday
   class Error < StandardError; end
-  class MissingDependency < Error; end
 
   class ClientError < Error
     attr_reader :response, :wrapped_exception
@@ -56,7 +55,7 @@ def initialize(ex = nil)
   class SSLError < ClientError
   end
 
-  [:MissingDependency, :ClientError, :ConnectionFailed, :ResourceNotFound,
+  [:ClientError, :ConnectionFailed, :ResourceNotFound,
    :ParsingError, :TimeoutError, :SSLError].each do |const|
     Error.const_set(const, Faraday.const_get(const))
   end

lib/faraday/options.rb

@@ -268,6 +268,50 @@ def new_builder(block)
     end
   end
 
+  # @!attribute method
+  #   @return [Symbol] HTTP method (`:get`, `:post`)
+  #
+  # @!attribute body
+  #   @return [String] The request body that will eventually be converted to a string.
+  #
+  # @!attribute url
+  #   @return [URI] URI instance for the current request.
+  #
+  # @!attribute request
+  #   @return [Hash] options for configuring the request.
+  #   Options for configuring the request.
+  #
+  #   - `:timeout`  open/read timeout Integer in seconds
+  #   - `:open_timeout` - read timeout Integer in seconds
+  #   - `:on_data`      - Proc for streaming
+  #   - `:proxy`        - Hash of proxy options
+  #       - `:uri`        - Proxy Server URI
+  #       - `:user`       - Proxy server username
+  #       - `:password`   - Proxy server password
+  #
+  # @!attribute request_headers
+  #   @return [Hash] HTTP Headers to be sent to the server.
+  #
+  # @!attribute ssl
+  #   @return [Hash] options for configuring SSL requests
+  #
+  # @!attribute parallel_manager
+  #   @return [Object] sent if the connection is in parallel mode
+  #
+  # @!attribute params
+  #   @return [Hash]
+  #
+  # @!attribute response
+  #   @return [Response]
+  #
+  # @!attribute response_headers
+  #   @return [Hash] HTTP headers from the server
+  #
+  # @!attribute status
+  #   @return [Integer] HTTP response status code
+  #
+  # @!attribute reason_phrase
+  #   @return [String]
   class Env < Options.new(:method, :body, :url, :request, :request_headers,
     :ssl, :parallel_manager, :params, :response, :response_headers, :status,
     :reason_phrase)
@@ -287,7 +331,10 @@ class Env < Options.new(:method, :body, :url, :request, :request_headers,
 
     def_delegators :request, :params_encoder
 
-    # Public
+    # Build a new Env from given value. Respects and updates `custom_members`.
+    #
+    # @param value [Object] a value fitting Option.from(v).
+    # @return [Env] from given value
     def self.from(value)
       env = super(value)
       if value.respond_to?(:custom_members)
@@ -296,7 +343,7 @@ def self.from(value)
       env
     end
 
-    # Public
+    # @param key [Object]
     def [](key)
       if in_member_set?(key)
         super(key)
@@ -305,7 +352,8 @@ def [](key)
       end
     end
 
-    # Public
+    # @param key [Object]
+    # @param value [Object]
     def []=(key, value)
       if in_member_set?(key)
         super(key, value)
@@ -314,28 +362,28 @@ def []=(key, value)
       end
     end
 
-    # Public
+    # @return [Boolean] true if status is in the set of {SuccessfulStatuses}.
     def success?
       SuccessfulStatuses.include?(status)
     end
 
-    # Public
+    # @return [Boolean] true if there's no body yet, and the method is in the set of {MethodsWithBodies}.
     def needs_body?
       !body && MethodsWithBodies.include?(method)
     end
 
-    # Public
+    # Sets content length to zero and the body to the empty string.
     def clear_body
       request_headers[ContentLength] = '0'
       self.body = ''
     end
 
-    # Public
+    # @return [Boolean] true if the status isn't in the set of {StatusesWithoutBody}.
     def parse_body?
       !StatusesWithoutBody.include?(status)
     end
 
-    # Public
+    # @return [Boolean] true if there is a parallel_manager
     def parallel?
       !!parallel_manager
     end
@@ -353,12 +401,12 @@ def inspect
       %(#<#{self.class}#{attrs.join(" ")}>)
     end
 
-    # Internal
+    # @private
     def custom_members
       @custom_members ||= {}
     end
 
-    # Internal
+    # @private
     if members.first.is_a?(Symbol)
       def in_member_set?(key)
         self.class.member_set.include?(key.to_sym)
@@ -369,7 +417,7 @@ def in_member_set?(key)
       end
     end
 
-    # Internal
+    # @private
     def self.member_set
       @member_set ||= Set.new(members)
     end

lib/faraday/parameters.rb

@@ -1,12 +1,20 @@
 require "forwardable"
 
 module Faraday
+  # This is the default encoder for Faraday requests.
+  # Using this encoder, parameters will be encoded respecting their structure,
+  # so you can send objects such as Arrays or Hashes as parameters for your requests.
   module NestedParamsEncoder
     class << self
       extend Forwardable
       def_delegators :'Faraday::Utils', :escape, :unescape
     end
 
+    # @param params [nil, Array, #to_hash] parameters to be encoded
+    #
+    # @return [String] the encoded params
+    #
+    # @raise [TypeError] if params can not be converted to a Hash
     def self.encode(params)
       return nil if params == nil
 
@@ -63,6 +71,11 @@ def self.encode(params)
       return buffer.chop
     end
 
+    # @param query [nil, String]
+    #
+    # @return [Array<Array, String>] the decoded params
+    #
+    # @raise [TypeError] if the nesting is incorrect
     def self.decode(query)
       return nil if query == nil
 
@@ -114,6 +127,7 @@ def self.decode(query)
 
     # Internal: convert a nested hash with purely numeric keys into an array.
     # FIXME: this is not compatible with Rack::Utils.parse_nested_query
+    # @!visibility private
     def self.dehash(hash, depth)
       hash.each do |key, value|
         hash[key] = dehash(value, depth + 1) if value.kind_of?(Hash)

lib/faraday/request.rb

@@ -1,6 +1,7 @@
 module Faraday
-  # Used to setup urls, params, headers, and the request body in a sane manner.
+  # Used to setup URLs, params, headers, and the request body in a sane manner.
   #
+  # @example
   #   @connection.post do |req|
   #     req.url 'http://localhost', 'a' => '1' # 'http://localhost?a=1'
   #     req.headers['b'] = '2' # Header
@@ -9,6 +10,18 @@ module Faraday
   #     req.body = 'abc'
   #   end
   #
+  # @!attribute method
+  #   @return [Symbol] the HTTP method of the Request
+  # @!attribute path
+  #   @return [URI, String] the path
+  # @!attribute params
+  #   @return [Hash] query parameters
+  # @!attribute headers
+  #   @return [Faraday::Utils::Headers] headers
+  # @!attribute body
+  #   @return [Hash] body
+  # @!attribute options
+  #   @return [RequestOptions] options
   class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
     extend MiddlewareRegistry
 
@@ -21,13 +34,19 @@ class Request < Struct.new(:method, :path, :params, :headers, :body, :options)
       :token_auth => [:TokenAuthentication, 'token_authentication'],
       :instrumentation => [:Instrumentation, 'instrumentation']
 
+    # @param request_method [String]
+    # @yield [request] for block customization, if block given
+    # @yieldparam request [Request]
+    # @return [Request]
     def self.create(request_method)
       new(request_method).tap do |request|
         yield(request) if block_given?
       end
     end
 
-    # Public: Replace params, preserving the existing hash type
+    # Replace params, preserving the existing hash type.
+    #
+    # @param hash [Hash] new params
     def params=(hash)
       if params
         params.replace hash
@@ -36,7 +55,9 @@ def params=(hash)
       end
     end
 
-    # Public: Replace request headers, preserving the existing hash type
+    # Replace request headers, preserving the existing hash type.
+    #
+    # @param hash [Hash] new headers
     def headers=(hash)
       if headers
         headers.replace hash
@@ -45,6 +66,11 @@ def headers=(hash)
       end
     end
 
+    # Update path and params.
+    #
+    # @param path [URI, String]
+    # @param params [Hash, nil]
+    # @return [void]
     def url(path, params = nil)
       if path.respond_to? :query
         if query = path.query
@@ -61,31 +87,19 @@ def url(path, params = nil)
       self.params.update(params) if params
     end
 
+    # @param key [Object] key to look up in headers
+    # @return [Object] value of the given header name
     def [](key)
       headers[key]
     end
 
+    # @param key [Object] key of header to write
+    # @param value [Object] value of header
     def []=(key, value)
       headers[key] = value
     end
 
-    # ENV Keys
-    # :method - a symbolized request method (:get, :post)
-    # :body   - the request body that will eventually be converted to a string.
-    # :url    - URI instance for the current request.
-    # :status           - HTTP response status code
-    # :request_headers  - hash of HTTP Headers to be sent to the server
-    # :response_headers - Hash of HTTP headers from the server
-    # :parallel_manager - sent if the connection is in parallel mode
-    # :request - Hash of options for configuring the request.
-    #   :timeout      - open/read timeout Integer in seconds
-    #   :open_timeout - read timeout Integer in seconds
-    #   :on_data      - Proc for streaming
-    #   :proxy        - Hash of proxy options
-    #     :uri        - Proxy Server URI
-    #     :user       - Proxy server username
-    #     :password   - Proxy server password
-    # :ssl - Hash of options for configuring SSL requests.
+    # @return [Env] the Env for this Request
     def to_env(connection)
       Env.new(method, body, connection.build_exclusive_url(path, params),
         options, headers, connection.ssl, connection.parallel_manager)