Merge with docrails

1 files changed, 33 insertions, 9 deletions

diff --git a/activesupport/lib/active_support/cache/mem_cache_store.rb b/activesupport/lib/active_support/cache/mem_cache_store.rb
index 5531c30b7f..f9a7fb1440 100644
--- a/activesupport/lib/active_support/cache/mem_cache_store.rb
+++ b/activesupport/lib/active_support/cache/mem_cache_store.rb
@@ -2,8 +2,19 @@ require 'memcache'
 
 module ActiveSupport
   module Cache
+    # A cache store implementation which stores data in Memcached:
+    # http://www.danga.com/memcached/
+    #
+    # This is currently the most popular cache store for production websites.
+    #
+    # Special features:
+    # - Clustering and load balancing. One can specify multiple memcached servers,
+    #   and MemCacheStore will load balance between all available servers. If a
+    #   server goes down, then MemCacheStore will ignore it until it goes back
+    #   online.
+    # - Time-based expiry support. See #write and the +:expires_in+ option.
     class MemCacheStore < Store
-      module Response
+      module Response # :nodoc:
         STORED      = "STORED\r\n"
         NOT_STORED  = "NOT_STORED\r\n"
         EXISTS      = "EXISTS\r\n"
@@ -13,6 +24,14 @@ module ActiveSupport
 
       attr_reader :addresses
 
+      # Creates a new MemCacheStore object, with the given memcached server
+      # addresses. Each address is either a host name, or a host-with-port string
+      # in the form of "host_name:port". For example:
+      #
+      #   ActiveSupport::Cache::MemCacheStore.new("localhost", "server-downstairs.localnetwork:8229")
+      #
+      # If no addresses are specified, then MemCacheStore will connect to
+      # localhost port 11211 (the default memcached port).
       def initialize(*addresses)
         addresses = addresses.flatten
         options = addresses.extract_options!
@@ -21,7 +40,7 @@ module ActiveSupport
         @data = MemCache.new(addresses, options)
       end
 
-      def read(key, options = nil)
+      def read(key, options = nil) # :nodoc:
         super
         @data.get(key, raw?(options))
       rescue MemCache::MemCacheError => e
@@ -29,8 +48,13 @@ module ActiveSupport
         nil
       end
 
-      # Set key = value. Pass :unless_exist => true if you don't
-      # want to update the cache if the key is already set.
+      # Writes a value to the cache.
+      #
+      # Possible options:
+      # - +:unless_exist+ - set to true if you don't want to update the cache
+      #   if the key is already set.
+      # - +:expires_in+ - the number of seconds that this value may stay in
+      #   the cache. See ActiveSupport::Cache::Store#write for an example.
       def write(key, value, options = nil)
         super
         method = options && options[:unless_exist] ? :add : :set
@@ -44,7 +68,7 @@ module ActiveSupport
         false
       end
 
-      def delete(key, options = nil)
+      def delete(key, options = nil) # :nodoc:
         super
         response = @data.delete(key, expires_in(options))
         response == Response::DELETED
@@ -53,13 +77,13 @@ module ActiveSupport
         false
       end
 
-      def exist?(key, options = nil)
+      def exist?(key, options = nil) # :nodoc:
         # Doesn't call super, cause exist? in memcache is in fact a read
         # But who cares? Reading is very fast anyway
         !read(key, options).nil?
       end
 
-      def increment(key, amount = 1)
+      def increment(key, amount = 1) # :nodoc:
         log("incrementing", key, amount)
 
         response = @data.incr(key, amount)
@@ -68,7 +92,7 @@ module ActiveSupport
         nil
       end
 
-      def decrement(key, amount = 1)
+      def decrement(key, amount = 1) # :nodoc:
         log("decrement", key, amount)
 
         response = @data.decr(key, amount)
@@ -77,7 +101,7 @@ module ActiveSupport
         nil
       end
 
-      def delete_matched(matcher, options = nil)
+      def delete_matched(matcher, options = nil) # :nodoc:
         super
         raise "Not supported by Memcache"
       end