Replace compatibility errors with documentation.

Leave compatibility stuff to Mechanize itself and just keep
http-cookie clean.

lib/http/cookie.rb

@@ -233,10 +233,25 @@ class HTTP::Cookie
     #
     # `logger`
     # : Logger object useful for debugging
-    def parse(set_cookie, options = nil, *_, &block)
+    #
-      _.empty? && !options.is_a?(String) or
+    # ### Compatibility Note for Mechanize::Cookie users
-        raise ArgumentError, 'HTTP::Cookie equivalent for Mechanize::Cookie.parse(uri, set_cookie[, log]) is HTTP::Cookie.parse(set_cookie, :origin => uri[, :logger => log]).'
+    #
-
+    # * Order of parameters is a slightly different in
+    #   `HTTP::Cookie.parse`.  Compare these:
+    #
+    #       Mechanize::Cookie.parse(uri, set_cookie[, log])
+    #
+    #       HTTP::Cookie.parse(set_cookie, :origin => uri[, :logger => # log])
+    #
+    # * `HTTP::Cookie.parse` does not yield nil nor include nil in an
+    #   returned array.  It simply ignores unparsable parts.
+    #
+    # * `HTTP::Cookie.parse` is made to follow RFC 6265 to the extent
+    #   not terribly breaking interoperability with broken
+    #   implementations.  In particular, it is capable of parsing
+    #   cookie definitions containing double-quotes just as
+    #   naturally expected.
+    def parse(set_cookie, options = nil, &block)
       if options
         logger = options[:logger]
         origin = options[:origin] and origin = URI(origin)
@@ -355,11 +370,6 @@ class HTTP::Cookie
     @domain = @domain_name.hostname
   end
 
-  # Used to exist in Mechanize::CookieJar.  Use #domain=().
-  def set_domain(domain)
-    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#set_domain() is #domain=().'
-  end
-
   # Returns the domain attribute value as a DomainName object.
   attr_reader :domain_name
 

lib/http/cookie_jar.rb

@@ -33,10 +33,25 @@ class HTTP::CookieJar
   # Adds a +cookie+ to the jar and return self.  If a given cookie has
   # no domain or path attribute values and the origin is unknown,
   # ArgumentError is raised.
-  def add(cookie, *_)
+  #
-    _.empty? or
+  # ### Compatibility Note for Mechanize::Cookie users
-      raise ArgumentError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#add(uri, cookie) is #add(cookie) after setting cookie.origin = uri.'
+  #
-
+  # In HTTP::Cookie, each cookie object can store its origin URI
+  # (cf. #origin).  While the origin URI of a cookie can be set
+  # manually by #origin=, one is typically given in its generation.
+  # To be more specific, HTTP::Cookie.new and HTTP::Cookie.parse both
+  # take an :origin option.
+  #
+  #   `HTTP::Cookie.parse`.  Compare these:
+  #
+  #       # Mechanize::Cookie
+  #       jar.add(origin, cookie)
+  #       jar.add!(cookie)    # no acceptance check is performed
+  #
+  #       # HTTP::Cookie
+  #       jar.origin = origin # if it doesn't have one
+  #       jar.add(cookie)     # acceptance check is performed
+  def add(cookie)
     if cookie.domain.nil? || cookie.path.nil?
       raise ArgumentError, "a cookie with unknown domain or path cannot be added"
     end
@@ -46,11 +61,6 @@ class HTTP::CookieJar
   end
   alias << add
 
-  # Used to exist in Mechanize::CookieJar.  Use #add().
-  def add!(cookie)
-    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#add!() is #add().'
-  end
-
   # Gets an array of cookies that should be sent for the URL/URI.
   def cookies(url)
     now = Time.now
@@ -156,11 +166,6 @@ class HTTP::CookieJar
     self
   end
 
-  # Used to exist in Mechanize::CookieJar.  Use #save().
-  def save_as(*args)
-    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#save_as() is #save().'
-  end
-
   # call-seq:
   #   jar.load(filename_or_io, **options)
   #   jar.load(filename_or_io, format = :yaml, **options)
@@ -223,11 +228,6 @@ class HTTP::CookieJar
     self
   end
 
-  # Used to exist in Mechanize::CookieJar.  Use #clear().
-  def clear!
-    raise NoMethodError, 'HTTP::Cookie equivalent for Mechanize::CookieJar#clear!() is #clear().'
-  end
-
   # Removes expired cookies and return self.
   def cleanup(session = false)
     @store.cleanup session

test/helper.rb

@@ -19,15 +19,3 @@ module Enumerable
     result
   end
 end
-
-module Test::Unit::Assertions
-  def assert_raises_with_message(exc, re, message = nil, &block)
-    e = nil
-    begin
-      block.call
-    rescue Exception => e
-    end
-    assert_instance_of(exc, e, message)
-    assert_match(re, e.message, message)
-  end
-end

test/test_http_cookie.rb

@@ -680,18 +680,4 @@ class TestHTTPCookie < Test::Unit::TestCase
     assert_equal true,  cookie.valid_for_uri?(URI('https://example.com'))
     assert_equal false, cookie.valid_for_uri?(URI('file:///'))
   end
-
-  def test_migration
-    assert_raises_with_message(ArgumentError, /equivalent/) {
-      HTTP::Cookie.parse('http://example.com/', 'key=value')
-    }
-    assert_raises_with_message(ArgumentError, /equivalent/) {
-      HTTP::Cookie.parse('http://example.com/', 'key=value', Object.new)
-    }
-
-    cookie = HTTP::Cookie.new('key', 'value')
-    assert_raises_with_message(NoMethodError, /equivalent/) {
-      cookie.set_domain('www.example.com')
-    }
-  end
 end

test/test_http_cookie_jar.rb

@@ -569,20 +569,4 @@ class TestHTTPCookieJar < Test::Unit::TestCase
       cookie.domain == cookie.value
     }
   end
-
-  def test_migration
-    cookie = HTTP::Cookie.new(cookie_values)
-    assert_raises_with_message(ArgumentError, /equivalent/) {
-      @jar.add('http://example.com/', cookie)
-    }
-    assert_raises_with_message(NoMethodError, /equivalent/) {
-      @jar.add!(cookie)
-    }
-    assert_raises_with_message(NoMethodError, /equivalent/) {
-      @jar.clear!()
-    }
-    assert_raises_with_message(NoMethodError, /equivalent/) {
-      @jar.save_as('/dev/null')
-    }
-  end
 end