Rework deprecation method for Error Namespaced Errors (#1035)

The version modeled off of activesupport's deprecations methods
was causing issues when classes inherited from the deprecated class.
Switch to a metaprogrammed class that warns upon initialization.

Failing spec for #1033

rename module to DeprecatedClass

Fix incorrect usage of rspec raise_error

WARNING: Using `expect { }.not_to raise_error(SpecificErrorClass)`
 risks false positives, since literally any other error would cause
 the expectation to pass, including those raised by Ruby
 (e.g. NoMethodError, NameError and ArgumentError), meaning the code
 you are intending to test may not even get reached. Instead consider
 using `expect { }.not_to raise_error` or
 `expect { }.to raise_error(DifferentSpecificErrorClass)`.

Update class doc

lib/faraday/deprecated_class.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Faraday
+  # @param old_klass [String] Old Namespaced Class
+  # @param new_klass [Class] New Class that the caller should use instead
+  #
+  # @return [Class] A modified version of new_klass that warns on
+  #   usage about deprecation.
+  module DeprecatedClass
+    def self.proxy_class(old_klass, new_klass)
+      Class.new(new_klass).tap do |k|
+        k.send(:define_method, :initialize) do |*args, &block|
+          @old_klass = old_klass
+          @new_klass = new_klass
+          warn
+          super(*args, &block)
+        end
+
+        k.send(:define_method, :warn) do
+          puts(
+            "DEPRECATION WARNING: #{@old_klass} is deprecated! " \
+            "Use #{@new_klass} instead."
+          )
+        end
+      end
+    end
+  end
+end

lib/faraday/error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'faraday/deprecated_constant'
+require 'faraday/deprecated_class'
 
 # Faraday namespace.
 module Faraday
@@ -105,7 +105,7 @@ class RetriableResponse < Error
      ParsingError TimeoutError SSLError RetriableResponse].each do |const|
     Error.const_set(
       const,
-      Faraday::DeprecatedConstant.new(
+      Faraday::DeprecatedClass.proxy_class(
         "Faraday::Error::#{const}",
         Faraday.const_get(const)
       )

spec/faraday/error_spec.rb

@@ -51,6 +51,10 @@
           "DEPRECATION WARNING: Faraday::Error::ClientError is deprecated! Use Faraday::ClientError instead.\n"
         )
       end
+
+      it 'allows backward-compatible class to be subclassed' do
+        expect { class CustomError < Faraday::Error::ClientError; end }.not_to raise_error
+      end
     end
 
     def with_warn_squelching