From a7575ae3df45eb245e42048f7523692fe5f64fd2 Mon Sep 17 00:00:00 2001 From: Akinori MUSHA Date: Wed, 27 Mar 2013 18:17:56 +0900 Subject: [PATCH] Improve documentation. --- README.md | 8 ++--- lib/http/cookie.rb | 6 ++-- lib/http/cookie_jar.rb | 46 ++++++++++++++++------------ lib/http/cookie_jar/hash_store.rb | 24 +++++++++------ lib/http/cookie_jar/mozilla_store.rb | 25 +++++++++++++++ 5 files changed, 74 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 1681c1e..7522e19 100644 --- a/README.md +++ b/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 - layer. If you want to tweak the internals of the hash storage, - try creating a new storage class referring to the default storage - class `HTTP::CookieJar::HashStore`. + `HTTP::CookieJar` since it has introduced an abstract store layer. + If you want to tweak the internals of the hash store, try creating + a new store class referring to the default store class + `HTTP::CookieJar::HashStore`. If you desperately need it you can access it by `jar.store.instance_variable_get(:@jar)`, but there is no diff --git a/lib/http/cookie.rb b/lib/http/cookie.rb index 8fcd4a7..d6584e2 100644 --- a/lib/http/cookie.rb +++ b/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 diff --git a/lib/http/cookie_jar.rb b/lib/http/cookie_jar.rb index 0e91823..3fb9295 100644 --- a/lib/http/cookie_jar.rb +++ b/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+ - # [:yaml] - # YAML structure (default) - # [:cookiestxt] - # Mozilla's cookies.txt format - # * +session+ - # [+true+] - # Save session cookies as well. - # [+false+] - # Do not save session cookies. (default) + # * `:format` + #
+ #
:yaml
+ #
YAML structure (default)
+ #
:cookiestxt
+ #
: Mozilla's cookies.txt format
+ #
+ # + # * `:session` + #
+ #
true
+ #
Save session cookies as well.
+ #
false
+ #
Do not save session cookies. (default)
+ #
# # 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+ - # [:yaml] - # YAML structure (default) - # [:cookiestxt] - # Mozilla's cookies.txt format + # * `:format` + #
+ #
:yaml
+ #
YAML structure (default)
+ #
:cookiestxt
+ #
: Mozilla's cookies.txt format
+ #
# # All options given are passed through to the underlying cookie # saver module. diff --git a/lib/http/cookie_jar/hash_store.rb b/lib/http/cookie_jar/hash_store.rb index 54528a7..0e2b824 100644 --- a/lib/http/cookie_jar/hash_store.rb +++ b/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,20 +17,26 @@ 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 = {} - # { - # hostname => { - # path => { - # name => cookie, - # ... - # }, + @jar = { + # hostname => { + # path => { + # name => cookie, # ... # }, # ... - # } + # }, + # ... + } @gc_index = 0 end diff --git a/lib/http/cookie_jar/mozilla_store.rb b/lib/http/cookie_jar/mozilla_store.rb index d5e67d2..60871c2 100644 --- a/lib/http/cookie_jar/mozilla_store.rb +++ b/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