Improve markups.

lib/http/cookie.rb

@@ -95,8 +95,8 @@ class HTTP::Cookie
   # The cookie domain.
   #
   # Setting a domain with a leading dot implies that the #for_domain
-  # flag should be turned on.  The setter accepts a `DomainName`
+  # flag should be turned on.  The setter accepts a DomainName object
-  # object as well as a string-like.
+  # as well as a string-like.
   #
   # :attr_accessor: domain
 
@@ -147,8 +147,8 @@ class HTTP::Cookie
   # string, downcased or not.
   #
   # This methods accepts any attribute name for which a setter method
-  # is defined.  Beware, however, any error (typically
+  # is defined.  Beware, however, any error (typically ArgumentError)
-  # `ArgumentError`) a setter method raises will be passed through.
+  # a setter method raises will be passed through.
   #
   # e.g.
   #
@@ -256,23 +256,22 @@ class HTTP::Cookie
     #
     # ### Compatibility Note for Mechanize::Cookie users
     #
-    # * Order of parameters changed in
+    # * Order of parameters changed in HTTP::Cookie.parse:
-    #   `HTTP::Cookie.parse`.  Compare these:
     #
     #         Mechanize::Cookie.parse(uri, set_cookie[, log])
     #
     #         HTTP::Cookie.parse(set_cookie, uri[, :logger => # log])
     #
-    # * `HTTP::Cookie.parse` does not accept nil for `set_cookie`.
+    # * HTTP::Cookie.parse does not accept nil for `set_cookie`.
     #
-    # * `HTTP::Cookie.parse` does not yield nil nor include nil in an
+    # * 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
+    # * 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
+    #   cookie definitions containing double-quotes just as naturally
-    #   naturally expected.
+    #   expected.
     def parse(set_cookie, origin, options = nil, &block)
       if options
         logger = options[:logger]

lib/http/cookie_jar.rb

@@ -19,13 +19,13 @@ class HTTP::CookieJar
   # : The store class that backs this jar. (default: `:hash`)
   # A symbol or an instance of a store class is accepted.  Symbols are
   # mapped to store classes, like `:hash` to
-  # `HTTP::CookieJar::HashStore` and `:mozilla` to
+  # HTTP::CookieJar::HashStore and `:mozilla` to
-  # `HTTP::CookieJar::MozillaStore`.
+  # HTTP::CookieJar::MozillaStore.
   #
   # Any options given are passed through to the initializer of the
   # specified store class.  For example, the `:mozilla`
-  # (`HTTP::CookieJar::MozillaStore`) store class requires a
+  # (HTTP::CookieJar::MozillaStore) store class requires a `:filename`
-  # `:filename` option.  See individual store classes for details.
+  # option.  See individual store classes for details.
   def initialize(options = nil)
     opthash = {
       :store => :hash,
@@ -57,8 +57,6 @@ class HTTP::CookieJar
   # To be more specific, HTTP::Cookie.new takes an `:origin` option
   # and HTTP::Cookie.parse takes one via the second argument.
   #
-  #   `HTTP::Cookie.parse`.  Compare these:
-  #
   #       # Mechanize::Cookie
   #       jar.add(origin, cookie)
   #       jar.add!(cookie)    # no acceptance check is performed
@@ -151,6 +149,7 @@ class HTTP::CookieJar
   # Available option keywords are below:
   #
   # * `:format`
+  #
   #     <dl class="rdoc-list note-list">
   #       <dt>:yaml</dt>
   #       <dd>YAML structure (default)</dd>
@@ -159,6 +158,7 @@ class HTTP::CookieJar
   #     </dl>
   #
   # * `:session`
+  #
   #     <dl class="rdoc-list note-list">
   #       <dt>true</dt>
   #       <dd>Save session cookies as well.</dd>
@@ -212,16 +212,17 @@ class HTTP::CookieJar
   #
   # Loads cookies recorded in a file or an IO in the format specified
   # into the jar and returns self.  If a given object responds to
-  # #read it is taken as an IO, or taken as a filename otherwise.
+  # \#read it is taken as an IO, or taken as a filename otherwise.
   #
   # Available option keywords are below:
   #
   # * `:format`
+  #
   #     <dl class="rdoc-list note-list">
   #       <dt>:yaml</dt>
   #       <dd>YAML structure (default)</dd>
   #       <dt>:cookiestxt</dt>
-  #     <dd>: Mozilla's cookies.txt format</dd>
+  #       <dd>Mozilla's cookies.txt format</dd>
   #     </dl>
   #
   # All options given are passed through to the underlying cookie