lib/http/cookie_jar/abstract_store.rb in http-cookie-1.0.0.pre12 vs lib/http/cookie_jar/abstract_store.rb in http-cookie-1.0.0

@@ -1,7 +1,9 @@
+# :markup: markdown
 require 'monitor'
 
+# An abstract superclass for all store classes.
 class HTTP::CookieJar::AbstractStore
   include MonitorMixin
 
   class << self
     @@class_map = {}
@@ -18,24 +20,29 @@
       rescue LoadError, IndexError
         raise IndexError, 'cookie store unavailable: %s' % symbol.inspect
       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 ||= {}
     @logger = options[:logger]
     # Initializes each instance variable of the same name as option
@@ -43,18 +50,25 @@
     default_options.each_pair { |key, default|
       instance_variable_set("@#{key}", options.fetch(key, default))
     }
   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
 
   # Iterates over all cookies that are not expired.
@@ -64,11 +78,13 @@
   # 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
   # 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
     #   synchronize {
     #     ...
@@ -76,17 +92,25 @@
     # end
     # self
   end
   include Enumerable
 
+  # Implements HTTP::CookieJar#empty?().
   def empty?
-    # true or false
+    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? }
     # else
     #   select(&:expired?)