Improve compatibility notes and overall markups.

README.md

@@ -1,6 +1,6 @@
 # HTTP::Cookie
 
-`HTTP::Cookie` is a ruby library to handle HTTP cookies in a way both
+HTTP::Cookie is a ruby library to handle HTTP cookies in a way both
 compliant with RFCs and compatible with today's major browsers.
 
 It was originally a part of the
@@ -60,14 +60,16 @@ Or install it yourself as:
     set_cookie_header_value = cookies.set_cookie_value(my_url)
 
 
-## Incompatibilities with `Mechanize::Cookie`/`CookieJar`
+## Incompatibilities with Mechanize::Cookie/CookieJar
 
 There are several incompatibilities between
-`Mechanize::Cookie`/`CookieJar` and `HTTP::Cookie`/`CookieJar`.  Below
+Mechanize::Cookie/CookieJar and HTTP::Cookie/CookieJar.  Below
-is how to rewrite existing code written for `Mechanize::Cookie` with
+is how to rewrite existing code written for Mechanize::Cookie with
-equivalent using `HTTP::Cookie`:
+equivalent using HTTP::Cookie:
 
-- `Mechanize::Cookie.parse`
+- Mechanize::Cookie.parse
+
+    The parameter order changed in HTTP::Cookie.parse.
 
         # before
         cookies1 = Mechanize::Cookie.parse(uri, set_cookie1)
@@ -77,18 +79,21 @@ equivalent using `HTTP::Cookie`:
         cookies1 = HTTP::Cookie.parse(set_cookie1, uri_or_url)
         cookies2 = HTTP::Cookie.parse(set_cookie2, uri_or_url, :logger => log)
 
-- `Mechanize::Cookie#version`, `#version=`
+- Mechanize::Cookie#version, #version=
 
     There is no longer a sense of version in HTTP cookie.  The only
     version number that has ever been defined was zero, and there will
     be no other version since the version attribute has been removed
     in RFC 6265.
 
-- `Mechanize::Cookie#comment`, `#comment=`
+- Mechanize::Cookie#comment, #comment=
 
     Ditto.  The comment attribute has been removed in RFC 6265.
 
-- `Mechanize::Cookie#set_domain`
+- Mechanize::Cookie#set_domain
+
+    This method was unintentionally made public.  Simply use
+    HTTP::Cookie#domain=.
 
         # before
         cookie.set_domain(domain)
@@ -96,7 +101,9 @@ equivalent using `HTTP::Cookie`:
         # after
         cookie.domain = domain
 
-- `Mechanize::CookieJar#add`, `#add!`
+- Mechanize::CookieJar#add, #add!
+
+    Always use HTTP::CookieJar#add.
 
         # before
         jar.add!(cookie1)
@@ -106,7 +113,9 @@ equivalent using `HTTP::Cookie`:
         jar.add(cookie1)
         cookie2.origin = uri; jar.add(cookie2)  # or specify origin in parse() or new()
 
-- `Mechanize::CookieJar#clear!`
+- Mechanize::CookieJar#clear!
+
+    Use HTTP::Cookiejar#clear.
 
         # before
         jar.clear!
@@ -114,7 +123,9 @@ equivalent using `HTTP::Cookie`:
         # after
         jar.clear
 
-- `Mechanize::CookieJar#save_as`
+- Mechanize::CookieJar#save_as
+
+    Use HTTP::CookieJar#save.
 
         # before
         jar.save_as(file)
@@ -122,34 +133,34 @@ equivalent using `HTTP::Cookie`:
         # after
         jar.save(file)
 
-- `Mechanize::CookieJar#jar`
+- Mechanize::CookieJar#jar
 
-    There is no direct access to the internal hash in
+    There is no direct access to the internal hash in HTTP::CookieJar
-    `HTTP::CookieJar` since it has introduced an abstract store layer.
+    since it has introduced an abstract store layer.  If you want to
-    If you want to tweak the internals of the hash store, try creating
+    tweak the internals of the hash store, try creating a new store
-    a new store class referring to the default store class
+    class referring to the default store class
-    `HTTP::CookieJar::HashStore`.
+    HTTP::CookieJar::HashStore.
 
     If you desperately need it you can access it by
     `jar.store.instance_variable_get(:@jar)`, but there is no
     guarantee that it will remain available in the future.
 
 
-`HTTP::Cookie`/`CookieJar` raise runtime errors to help migration, so
+HTTP::Cookie/CookieJar raise runtime errors to help migration, so
 after replacing the class names, try running your test code once to
 find out how to fix your code base.
 
 ### File formats
 
-The YAML serialization format has changed, and `HTTP::CookieJar#load`
+The YAML serialization format has changed, and HTTP::CookieJar#load
 cannot import what is written in a YAML file saved by
-`Mechanize::CookieJar#save_as`.  `HTTP::CookieJar#load` will not raise
+Mechanize::CookieJar#save_as.  HTTP::CookieJar#load will not raise an
-an exception if an incompatible YAML file is given, but the content is
+exception if an incompatible YAML file is given, but the content is
 silently ignored.
 
 Note that there is (obviously) no forward compatibillity with this.
-Trying to load a YAML file saved by `HTTP::CookieJar` with
+Trying to load a YAML file saved by HTTP::CookieJar with
-`Mechanize::CookieJar` will fail in runtime error.
+Mechanize::CookieJar will fail in runtime error.
 
 On the other hand, there has been (and will ever be) no change in the
 cookies.txt format, so use it instead if compatibility is significant.