Improve documentation.

README.md

@@ -114,10 +114,10 @@ equivalent using `HTTP::Cookie`:
 - `Mechanize::CookieJar#jar`
 
     There is no direct access to the internal hash in
-    `HTTP::CookieJar` since it has introduced an abstract storage
+    `HTTP::CookieJar` since it has introduced an abstract store layer.
-    layer.  If you want to tweak the internals of the hash storage,
+    If you want to tweak the internals of the hash store, try creating
-    try creating a new storage class referring to the default storage
+    a new store class referring to the default store class
-    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

lib/http/cookie.rb

@@ -240,14 +240,14 @@ class HTTP::Cookie
     #
     # Available option keywords are below:
     #
-    # `origin`
+    # :origin
     # : The cookie's origin URI/URL
     #
-    # `date`
+    # :date
     # : The base date used for interpreting Max-Age attribute values
     #   instead of the current time
     #
-    # `logger`
+    # :logger
     # : Logger object useful for debugging
     #
     # ### Compatibility Note for Mechanize::Cookie users

lib/http/cookie_jar.rb

@@ -1,3 +1,4 @@
+# :markup: markdown
 require 'http/cookie'
 
 ##
@@ -44,7 +45,7 @@ class HTTP::CookieJar
     @store = other.instance_eval { @store.dup }
   end
 
-  # Adds a +cookie+ to the jar and return self.  If a given cookie has
+  # 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.
   #
@@ -83,7 +84,7 @@ class HTTP::CookieJar
     }.sort
   end
 
-  # Tests if the jar is empty.  If +url+ is given, tests if there is
+  # Tests if the jar is empty.  If `url` is given, tests if there is
   # no cookie for the URL.
   def empty?(url = nil)
     if url
@@ -96,12 +97,12 @@ class HTTP::CookieJar
 
   # Iterates over all cookies that are not expired.
   #
-  # An optional argument +uri+ specifies a URI/URL indicating the
+  # An optional argument `uri` specifies a URI/URL indicating the
   # destination of the cookies being selected.  Every cookie yielded
   # should be good to send to the given URI,
   # i.e. cookie.valid_for_uri?(uri) evaluates to true.
   #
-  # If (and only if) the +uri+ option is given, last access time of
+  # If (and only if) the `uri` option is given, last access time of
   # each cookie is updated to the current time.
   def each(uri = nil, &block)
     block_given? or return enum_for(__method__, uri)
@@ -126,16 +127,21 @@ class HTTP::CookieJar
   #
   # Available option keywords are below:
   #
-  # * +format+
+  # * `:format`
-  #   [<tt>:yaml</tt>]
+  #   <dl class="rdoc-list note-list">
-  #     YAML structure (default)
+  #     <dt>:yaml</dt>
-  #   [<tt>:cookiestxt</tt>]
+  #     <dd>YAML structure (default)</dd>
-  #     Mozilla's cookies.txt format
+  #     <dt>:cookiestxt</dt>
-  # * +session+
+  #     <dd>: Mozilla's cookies.txt format</dd>
-  #   [+true+]
+  #   </dl>
-  #     Save session cookies as well.
+  #
-  #   [+false+]
+  # * `:session`
-  #     Do not save session cookies. (default)
+  #   <dl class="rdoc-list note-list">
+  #     <dt>true</dt>
+  #     <dd>Save session cookies as well.</dd>
+  #     <dt>false</dt>
+  #     <dd>Do not save session cookies. (default)</dd>
+  #   </dl>
   #
   # All options given are passed through to the underlying cookie
   # saver module.
@@ -187,11 +193,13 @@ class HTTP::CookieJar
   #
   # Available option keywords are below:
   #
-  # * +format+
+  # * `:format`
-  #   [<tt>:yaml</tt>]
+  #   <dl class="rdoc-list note-list">
-  #     YAML structure (default)
+  #     <dt>:yaml</dt>
-  #   [<tt>:cookiestxt</tt>]
+  #     <dd>YAML structure (default)</dd>
-  #     Mozilla's cookies.txt format
+  #     <dt>:cookiestxt</dt>
+  #     <dd>: Mozilla's cookies.txt format</dd>
+  #   </dl>
   #
   # All options given are passed through to the underlying cookie
   # saver module.

lib/http/cookie_jar/hash_store.rb

@@ -9,7 +9,7 @@ end
 # :startdoc:
 
 class HTTP::CookieJar
-  # A store class that uses a hash of hashes.
+  # A store class that uses a hash-based cookie store.
   class HashStore < AbstractStore
     def default_options
       {
@@ -17,11 +17,17 @@ class HTTP::CookieJar
       }
     end
 
+    # Generates a hash based cookie store.
+    #
+    # Available option keywords are as below:
+    #
+    # :gc_threshold
+    # : GC threshold; A GC happens when this many times cookies have
+    # been stored (default: `HTTP::Cookie::MAX_COOKIES_TOTAL / 20`)
     def initialize(options = nil)
       super
 
-      @jar = {}
+      @jar = {
-      # {
       # hostname => {
       #   path => {
       #     name => cookie,
@@ -30,7 +36,7 @@ class HTTP::CookieJar
       #   ...
       # },
       # ...
-      # }
+      }
 
       @gc_index = 0
     end

lib/http/cookie_jar/mozilla_store.rb

@@ -1,7 +1,10 @@
+# :markup: markdown
 require 'http/cookie_jar'
 require 'sqlite3'
 
 class HTTP::CookieJar
+  # A store class that uses Mozilla compatible SQLite3 database as
+  # backing store.
   class MozillaStore < AbstractStore
     SCHEMA_VERSION = 5
 
@@ -26,6 +29,27 @@ class HTTP::CookieJar
       appId inBrowserElement
     ]
 
+    # Generates a Mozilla cookie store.  If the file does not exist,
+    # it is created.  If it does and its schema is old, it is
+    # automatically upgraded with a new schema keeping the existing
+    # data.
+    #
+    # Available option keywords are as below:
+    #
+    # :filename
+    # : A file name of the SQLite3 database to open.  This option is
+    # mandatory.
+    #
+    # :gc_threshold
+    # : GC threshold; A GC happens when this many times cookies have
+    # been stored (default: `HTTP::Cookie::MAX_COOKIES_TOTAL / 20`)
+    #
+    # :app_id
+    # : application ID (default: `0`) to have per application jar.
+    #
+    # :in_browser_element
+    # : a flag to tell if cookies are stored in an in browser
+    # element. (default: `false`)
     def initialize(options = nil)
       super
 
@@ -39,6 +63,7 @@ class HTTP::CookieJar
       @gc_index = 0
     end
 
+    # Returns the schema version of the database.
     def schema_version
       @schema_version ||= @db.execute("PRAGMA user_version").first[0]
     rescue SQLite3::SQLException