Update rdoc and comments.

lib/http/cookie.rb

@@ -69,10 +69,9 @@ class HTTP::Cookie
 
   # The cookie name.  It may not be nil or empty.
   #
-  # Trying to set a value with the normal setter method will raise
+  # Assign a string containing any of the following characters will
-  # ArgumentError only when it contains any of these characters:
+  # raise ArgumentError: control characters (`\x00-\x1F` and `\x7F`),
-  # control characters (\x00-\x1F and \x7F), space and separators
+  # space and separators `,;\"=`.
-  # `,;\"=`.
   #
   # Note that RFC 6265 4.1.1 lists more characters disallowed for use
   # in a cookie name, which are these: `<>@:/[]?{}`.  Using these
@@ -82,9 +81,8 @@ class HTTP::Cookie
 
   # The cookie value.
   #
-  # Trying to set a value with the normal setter method will raise an
+  # Assign a string containing a control character (`\x00-\x1F` and
-  # ArgumentError only when it contains any of these characters:
+  # `\x7F`) will raise ArgumentError.
-  # control characters (\x00-\x1F and \x7F).
   #
   # Note that RFC 6265 4.1.1 lists more characters disallowed for use
   # in a cookie value, which are these: ` ",;\`.  Using these
@@ -566,16 +564,15 @@ class HTTP::Cookie
     acceptable_from_uri?(uri) && HTTP::Cookie.path_match?(@path, uri.path)
   end
 
-  # Returns a string for use in a Cookie header value,
+  # Returns a string for use in the Cookie header, i.e. `name=value`
-  # i.e. "name=value".
+  # or `name="value"`.
   def cookie_value
     "#{@name}=#{Scanner.quote(@value)}"
   end
   alias to_s cookie_value
 
-  # Returns a string for use in a Set-Cookie header value.  If the
+  # Returns a string for use in the Set-Cookie header.  If the cookie
-  # cookie does not have an origin set, one must be given from the
+  # does not have an origin set, one must be given from the argument.
-  # argument.
   #
   # This method does not check if this cookie will be accepted from
   # the origin.
@@ -608,7 +605,6 @@ class HTTP::Cookie
     '#<%s:' % self.class << PERSISTENT_PROPERTIES.map { |key|
       '%s=%s' % [key, instance_variable_get(:"@#{key}").inspect]
     }.join(', ') << ' origin=%s>' % [@origin ? @origin.to_s : 'nil']
-
   end
 
   # Compares the cookie with another.  When there are many cookies with

lib/http/cookie/scanner.rb

@@ -151,7 +151,7 @@ class HTTP::Cookie::Scanner < StringScanner
   end
 
   def scan_cookie
-    # cf. RFC 6265 5.2
+    # RFC 6265 4.1.1 & 5.2
     until eos?
       start = pos
       len = nil
@@ -171,6 +171,8 @@ class HTTP::Cookie::Scanner < StringScanner
 
       case
       when skip(/,/)
+        # The comma is used as separator for concatenating multiple
+        # values of a header.
         len = (pos - 1) - start
         break
       when skip(/;/)

lib/http/cookie_jar.rb

@@ -169,7 +169,7 @@ class HTTP::CookieJar
   #       <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>
   #
   # * `:session`