rubocop: fix Style/Documentation offenses (#951)

* rubocop: fix Style/Documentation offenses

* no test dir

* use @see tag

* put @example after @params, before @return

.rubocop.yml

@@ -16,3 +16,6 @@ Metrics/LineLength:
 Style/DoubleNegation:
   Enabled: false
 
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'

.rubocop_todo.yml

@@ -1,49 +1,29 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-03-07 10:32:00 -0700 using RuboCop version 0.65.0.
+# on 2019-03-20 12:08:09 -0600 using RuboCop version 0.65.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 38
+# Offense count: 37
 Metrics/AbcSize:
-  Max: 82
+  Max: 67
 
 # Offense count: 5
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
   Max: 233
 
-# Offense count: 16
+# Offense count: 17
 Metrics/CyclomaticComplexity:
   Max: 16
 
-# Offense count: 42
+# Offense count: 47
 # Configuration parameters: CountComments, ExcludedMethods.
 Metrics/MethodLength:
-  Max: 57
+  Max: 48
 
 # Offense count: 13
 Metrics/PerceivedComplexity:
   Max: 16
-
-# Offense count: 16
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'lib/faraday/adapter/em_http.rb'
-    - 'lib/faraday/autoload.rb'
-    - 'lib/faraday/dependency_loader.rb'
-    - 'lib/faraday/encoders/flat_params_encoder.rb'
-    - 'lib/faraday/middleware.rb'
-    - 'lib/faraday/options/connection_options.rb'
-    - 'lib/faraday/options/proxy_options.rb'
-    - 'lib/faraday/options/request_options.rb'
-    - 'lib/faraday/request/retry.rb'
-    - 'lib/faraday/request/token_authentication.rb'
-    - 'lib/faraday/response.rb'
-    - 'lib/faraday/response/logger.rb'
-    - 'lib/faraday/response/raise_error.rb'
-    - 'lib/faraday/utils.rb'

lib/faraday/adapter/em_http.rb

@@ -6,6 +6,8 @@ class Adapter
     # requests when in an EM reactor loop, or for making parallel requests in
     # synchronous code.
     class EMHttp < Faraday::Adapter
+      # Options is a module containing helpers to convert the Faraday env object
+      # into options hashes for EMHTTP method calls.
       module Options
         # @return [Hash]
         def connection_config(env)

lib/faraday/autoload.rb

@@ -21,7 +21,6 @@ module AutoloadHelper
     #   # requires faraday/foo/bar to load Faraday::Bar.
     #   Faraday::Bar
     #
-    #
     # @return [void]
     def autoload_all(prefix, options)
       if prefix =~ %r{^faraday(/|$)}i
@@ -54,6 +53,8 @@ def all_loaded_constants
     end
   end
 
+  # Adapter is the base class for all Faraday adapters.
+  # @see lib/faraday/adapter.rb Original class location
   class Adapter
     extend AutoloadHelper
     autoload_all 'faraday/adapter',
@@ -69,6 +70,8 @@ class Adapter
                  HTTPClient: 'httpclient'
   end
 
+  # Request represents a single HTTP request for a Faraday adapter to make.
+  # @see lib/faraday/request.rb Original class location
   class Request
     extend AutoloadHelper
     autoload_all 'faraday/request',
@@ -81,6 +84,8 @@ class Request
                  Instrumentation: 'instrumentation'
   end
 
+  # Response represents the returned value of a sent Faraday request.
+  # @see lib/faraday/response.rb Original class location
   class Response
     extend AutoloadHelper
     autoload_all 'faraday/response',

lib/faraday/dependency_loader.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Faraday
+  # DependencyLoader helps Faraday adapters and middleware load dependencies.
   module DependencyLoader
     attr_reader :load_error
 

lib/faraday/encoders/flat_params_encoder.rb

@@ -1,12 +1,25 @@
 # frozen_string_literal: true
 
 module Faraday
+  # FlatParamsEncoder manages URI params as a flat hash. Any Array values repeat
+  # the parameter multiple times.
   module FlatParamsEncoder
     class << self
       extend Forwardable
       def_delegators :'Faraday::Utils', :escape, :unescape
     end
 
+    # Encode converts the given param into a URI querystring. Keys and values
+    # will converted to strings and appropriately escaped for the URI.
+    #
+    # @param params [Hash] query arguments to convert.
+    #
+    # @example
+    #
+    #   encode({a: %w[one two three], b: true, c: "C"})
+    #   # => 'a=one&a=two&a=three&b=true&c=C'
+    #
+    # @return [String] the URI querystring (without the leading '?')
     def self.encode(params)
       return nil if params.nil?
 
@@ -44,6 +57,16 @@ def self.encode(params)
       buffer.chop
     end
 
+    # Decode converts the given URI querystring into a hash.
+    #
+    # @param query [String] query arguments to parse.
+    #
+    # @example
+    #
+    #   decode('a=one&a=two&a=three&b=true&c=C')
+    #   # => {"a"=>["one", "two", "three"], "b"=>"true", "c"=>"C"}
+    #
+    # @return [Hash] parsed keys and value strings from the querystring.
     def self.decode(query)
       return nil if query.nil?
 

lib/faraday/middleware.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Faraday
+  # Middleware is the basic base class of any Faraday middleware.
   class Middleware
     extend MiddlewareRegistry
     extend DependencyLoader

lib/faraday/options/connection_options.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Faraday
+  # ConnectionOptions contains the configurable properties for a Faraday
+  # connection object.
   class ConnectionOptions < Options.new(:request, :proxy, :ssl, :builder, :url,
                                         :parallel_manager, :params, :headers,
                                         :builder_class)

lib/faraday/options/proxy_options.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Faraday
+  # ProxyOptions contains the configurable properties for the proxy
+  # configuration used when making an HTTP request.
   class ProxyOptions < Options.new(:uri, :user, :password)
     extend Forwardable
     def_delegators :uri, :scheme, :scheme=, :host, :host=, :port, :port=,

lib/faraday/options/request_options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Faraday
+  # RequestOptions contains the configurable properties for a Faraday request.
   class RequestOptions < Options.new(:params_encoder, :proxy, :bind,
                                      :timeout, :open_timeout, :write_timeout,
                                      :boundary, :oauth, :context, :on_data)

lib/faraday/request/retry.rb

@@ -29,6 +29,7 @@ class Retry < Faraday::Middleware
       ].freeze
       IDEMPOTENT_METHODS = %i[delete get head options put].freeze
 
+      # Options contains the configurable parameters for the Retry middleware.
       class Options < Faraday::Options.new(:max, :interval, :max_interval,
                                            :interval_randomness,
                                            :backoff_factor, :exceptions,

lib/faraday/request/token_authentication.rb

@@ -2,6 +2,8 @@
 
 module Faraday
   class Request
+    # TokenAuthentication is a middleware that adds a 'Token' header to a
+    # Faraday request.
     class TokenAuthentication < load_middleware(:authorization)
       # Public
       def self.header(token, options = nil)

lib/faraday/response.rb

@@ -3,6 +3,7 @@
 require 'forwardable'
 
 module Faraday
+  # Response represents an HTTP response from making an HTTP request.
   class Response
     # Used for simple response middleware.
     class Middleware < Faraday::Middleware

lib/faraday/response/logger.rb

@@ -5,6 +5,9 @@
 
 module Faraday
   class Response
+    # Logger is a middleware that logs internal events in the HTTP request
+    # lifecycle to a given Logger object. By default, this logs to STDOUT. See
+    # Faraday::Logging::Formatter to see specifically what is logged.
     class Logger < Middleware
       def initialize(app, logger = nil, options = {})
         super(app)

lib/faraday/response/raise_error.rb

@@ -2,6 +2,8 @@
 
 module Faraday
   class Response
+    # RaiseError is a Faraday middleware that raises exceptions on common HTTP
+    # client or server error responses.
     class RaiseError < Middleware
       # rubocop:disable Naming/ConstantName
       ClientErrorStatuses = (400...500).freeze

lib/faraday/utils.rb

@@ -4,6 +4,7 @@
 require 'faraday/utils/params_hash'
 
 module Faraday
+  # Utils contains various static helper methods.
   module Utils
     module_function