Improve rdoc.

lib/http/cookie.rb

@@ -87,7 +87,7 @@ class HTTP::Cookie
   # The Expires attribute value as a Time object.
   #
   # The setter method accepts a Time object, a string representation
-  # of date/time, or `nil`.
+  # of date/time that Time.parse can understand, or `nil`.
   #
   # Setting this value resets #max_age to nil.  When #max_age is
   # non-nil, #expires returns `created_at + max_age`.
@@ -340,7 +340,7 @@ class HTTP::Cookie
   attr_reader :name
 
   # See #name.
-  def name=(name)
+  def name= name
     name = (String.try_convert(name) or
       raise TypeError, "#{name.class} is not a String")
     if name.empty?
@@ -357,7 +357,7 @@ class HTTP::Cookie
   attr_reader :value
 
   # See #value.
-  def value=(value)
+  def value= value
     if value.nil?
       self.expires = UNIX_EPOCH
       return @value = ''
@@ -376,7 +376,7 @@ class HTTP::Cookie
   attr_reader :domain
 
   # See #domain.
-  def domain=(domain)
+  def domain= domain
     case domain
     when nil
       @for_domain = false
@@ -434,7 +434,7 @@ class HTTP::Cookie
   attr_reader :path
 
   # See #path.
-  def path=(path)
+  def path= path
     path = (String.try_convert(path) or
       raise TypeError, "#{path.class} is not a String")
     @path = path.start_with?('/') ? path : '/'
@@ -443,7 +443,7 @@ class HTTP::Cookie
   attr_reader :origin
 
   # See #origin.
-  def origin=(origin)
+  def origin= origin
     return origin if origin == @origin
     @origin.nil? or
       raise ArgumentError, "origin cannot be changed once it is set"
@@ -479,7 +479,7 @@ class HTTP::Cookie
   end
 
   # See #expires.
-  def expires=(t)
+  def expires= t
     case t
     when nil, Time
     else
@@ -496,7 +496,7 @@ class HTTP::Cookie
   attr_reader :max_age
 
   # See #max_age.
-  def max_age=(sec)
+  def max_age= sec
     @expires = nil
     case sec
     when Integer, nil
@@ -632,7 +632,7 @@ class HTTP::Cookie
 
   # Compares the cookie with another.  When there are many cookies with
   # the same name for a URL, the value of the smallest must be used.
-  def <=>(other)
+  def <=> other
     # RFC 6265 5.4
     # Precedence: 1. longer path  2. older creation
     (@name <=> other.name).nonzero? ||

lib/http/cookie_jar.rb

@@ -59,6 +59,7 @@ class HTTP::CookieJar
     end
   end
 
+  # The copy constructor.  Not all backend store classes support cloning.
   def initialize_copy(other)
     @store = other.instance_eval { @store.dup }
   end
@@ -136,7 +137,7 @@ class HTTP::CookieJar
   #
   # 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)
+  def each(uri = nil, &block) # :yield: cookie
     block_given? or return enum_for(__method__, uri)
 
     if uri
@@ -207,7 +208,7 @@ class HTTP::CookieJar
   #     </dl>
   #
   # All options given are passed through to the underlying cookie
-  # saver module.
+  # saver module's constructor.
   def save(writable, *options)
     opthash = {
       :format => :yaml,
@@ -266,7 +267,7 @@ class HTTP::CookieJar
   #     </dl>
   #
   # All options given are passed through to the underlying cookie
-  # saver module.
+  # saver module's constructor.
   def load(readable, *options)
     opthash = {
       :format => :yaml,
@@ -311,7 +312,8 @@ class HTTP::CookieJar
     self
   end
 
-  # Removes expired cookies and returns self.
+  # Removes expired cookies and returns self.  If `session` is true,
+  # all session cookies are removed as well.
   def cleanup(session = false)
     @store.cleanup session
     self

lib/http/cookie_jar/abstract_saver.rb

@@ -1,3 +1,6 @@
+# :markup: markdown
+
+# An abstract superclass for all saver classes.
 class HTTP::CookieJar::AbstractSaver
   class << self
     @@class_map = {}
@@ -16,20 +19,25 @@ class HTTP::CookieJar::AbstractSaver
       end
     end
 
-    def inherited(subclass)
+    def inherited(subclass) # :nodoc:
       @@class_map[class_to_symbol(subclass)] = subclass
     end
 
-    def class_to_symbol(klass)
+    def class_to_symbol(klass) # :nodoc:
       klass.name[/[^:]+?(?=Saver$|$)/].downcase.to_sym
     end
   end
 
+  # Defines options and their default values.
   def default_options
     # {}
   end
   private :default_options
 
+  # :call-seq:
+  #   new(**options)
+  #
+  # Called by the constructor of each subclass using super().
   def initialize(options = nil)
     options ||= {}
     @logger  = options[:logger]
@@ -41,10 +49,16 @@ class HTTP::CookieJar::AbstractSaver
     }
   end
 
+  # Implements HTTP::CookieJar#save().
+  #
+  # This is an abstract method that each subclass must override.
   def save(io, jar)
     # self
   end
 
+  # Implements HTTP::CookieJar#load().
+  #
+  # This is an abstract method that each subclass must override.
   def load(io, jar)
     # self
   end

lib/http/cookie_jar/abstract_store.rb

@@ -1,5 +1,7 @@
+# :markup: markdown
 require 'monitor'
 
+# An abstract superclass for all store classes.
 class HTTP::CookieJar::AbstractStore
   include MonitorMixin
 
@@ -20,20 +22,25 @@ class HTTP::CookieJar::AbstractStore
       end
     end
 
-    def inherited(subclass)
+    def inherited(subclass) # :nodoc:
       @@class_map[class_to_symbol(subclass)] = subclass
     end
 
-    def class_to_symbol(klass)
+    def class_to_symbol(klass) # :nodoc:
       klass.name[/[^:]+?(?=Store$|$)/].downcase.to_sym
     end
   end
 
+  # Defines options and their default values.
   def default_options
     # {}
   end
   private :default_options
 
+  # :call-seq:
+  #   new(**options)
+  #
+  # Called by the constructor of each subclass using super().
   def initialize(options = nil)
     super() # MonitorMixin
     options ||= {}
@@ -45,14 +52,21 @@ class HTTP::CookieJar::AbstractStore
     }
   end
 
+  # This is an abstract method that each subclass must override.
   def initialize_copy(other)
     # self
   end
 
+  # Implements HTTP::CookieJar#add().
+  #
+  # This is an abstract method that each subclass must override.
   def add(cookie)
     # self
   end
 
+  # Implements HTTP::CookieJar#delete().
+  #
+  # This is an abstract method that each subclass must override.
   def delete(cookie)
     # self
   end
@@ -66,7 +80,9 @@ class HTTP::CookieJar::AbstractStore
   #
   # 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)
+  #
+  # This is an abstract method that each subclass must override.
+  def each(uri = nil, &block) # :yield: cookie
     # if uri
     #   ...
     # else
@@ -78,15 +94,22 @@ class HTTP::CookieJar::AbstractStore
   end
   include Enumerable
 
+  # Implements HTTP::CookieJar#empty?().
   def empty?
     each { return false }
     true
   end
 
+  # Implements HTTP::CookieJar#clear().
+  #
+  # This is an abstract method that each subclass must override.
   def clear
     # self
   end
 
+  # Implements HTTP::CookieJar#cleanup().
+  #
+  # This is an abstract method that each subclass must override.
   def cleanup(session = false)
     # if session
     #   select { |cookie| cookie.session? || cookie.expired? }

lib/http/cookie_jar/cookiestxt_saver.rb

@@ -1,9 +1,25 @@
+# :markup: markdown
 require 'http/cookie_jar'
 
 # CookiestxtSaver saves and loads cookies in the cookies.txt format.
 class HTTP::CookieJar::CookiestxtSaver < HTTP::CookieJar::AbstractSaver
-  True  = "TRUE"
-  False = "FALSE"
+  # :singleton-method: new
+  # :call-seq:
+  #   new(**options)
+  #
+  # Available option keywords are below:
+  #
+  # * `:header`
+  #
+  #     Specifies the header line not including a line feed, which is
+  #     only used by #save().  None is output if nil is
+  #     given. (default: `"# HTTP Cookie File"`)
+  #
+  # * `:linefeed`
+  #
+  #     Specifies the line separator (default: `"\n"`).
+
+  ##
 
   def save(io, jar)
     io.puts @header if @header
@@ -28,8 +44,13 @@ class HTTP::CookieJar::CookiestxtSaver < HTTP::CookieJar::AbstractSaver
     }
   end
 
+  # :stopdoc:
+  True  = "TRUE"
+  False = "FALSE"
+
   HTTPONLY_PREFIX = '#HttpOnly_'
   RE_HTTPONLY_PREFIX = /\A#{HTTPONLY_PREFIX}/
+  # :startdoc:
 
   # Serializes the cookie into a cookies.txt line.
   def cookie_to_record(cookie)

lib/http/cookie_jar/hash_store.rb

@@ -1,3 +1,4 @@
+# :markup: markdown
 require 'http/cookie_jar'
 
 class HTTP::CookieJar
@@ -18,6 +19,9 @@ class HTTP::CookieJar
       }
     end
 
+    # :call-seq:
+    #   new(**options)
+    #
     # Generates a hash based cookie store.
     #
     # Available option keywords are as below:
@@ -42,6 +46,7 @@ class HTTP::CookieJar
       @gc_index = 0
     end
 
+    # The copy constructor.  This store class supports cloning.
     def initialize_copy(other)
       @jar = Marshal.load(Marshal.dump(other.instance_variable_get(:@jar)))
     end
@@ -59,7 +64,7 @@ class HTTP::CookieJar
       self
     end
 
-    def each(uri = nil)
+    def each(uri = nil) # :yield: cookie
       now = Time.now
       if uri
         thost = DomainName.new(uri.host)

lib/http/cookie_jar/mozilla_store.rb

@@ -68,6 +68,9 @@ class HTTP::CookieJar
     end
     # :startdoc:
 
+    # :call-seq:
+    #   new(**options)
+    #
     # 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
@@ -109,6 +112,7 @@ class HTTP::CookieJar
       @gc_index = 0
     end
 
+    # Raises TypeError.  Cloning is inhibited in this store class.
     def initialize_copy(other)
       raise TypeError, 'can\'t clone %s' % self.class
     end
@@ -138,7 +142,7 @@ class HTTP::CookieJar
 
     protected
 
-    def schema_version=(version)
+    def schema_version= version
       @db.execute("PRAGMA user_version = %d" % version)
       @schema_version = version
     end
@@ -329,7 +333,7 @@ class HTTP::CookieJar
               expiry >= :expiry
     SQL
 
-    def each(uri = nil, &block)
+    def each(uri = nil, &block) # :yield: cookie
       now = Time.now
       if uri
         thost = DomainName.new(uri.host)

lib/http/cookie_jar/yaml_saver.rb

@@ -1,9 +1,20 @@
+# :markup: markdown
 require 'http/cookie_jar'
 require 'psych' if !defined?(YAML) && RUBY_VERSION == "1.9.2"
 require 'yaml'
 
-# YAMLSaver saves and loads cookies in the YAML format.
+# YAMLSaver saves and loads cookies in the YAML format.  It can load a
+# YAML file saved by Mechanize, but the saving format is not
+# compatible with older versions of Mechanize (< 2.7).
 class HTTP::CookieJar::YAMLSaver < HTTP::CookieJar::AbstractSaver
+  # :singleton-method: new
+  # :call-seq:
+  #   new(**options)
+  #
+  # There is no option keyword supported at the moment.
+
+  ##
+
   def save(io, jar)
     YAML.dump(@session ? jar.to_a : jar.reject(&:session?), io)
   end