Merge branch 'master' of github.com:rails/docrails

1 files changed, 22 insertions, 1 deletions

diff --git a/actionpack/lib/action_dispatch/http/headers.rb b/actionpack/lib/action_dispatch/http/headers.rb
index 788eed8b89..3e607bbde1 100644
--- a/actionpack/lib/action_dispatch/http/headers.rb
+++ b/actionpack/lib/action_dispatch/http/headers.rb
@@ -1,5 +1,10 @@
 module ActionDispatch
   module Http
+    # Provides access to the request's HTTP headers from the environment.
+    #
+    #   env     = { "CONTENT_TYPE" => "text/plain" }
+    #   headers = ActionDispatch::Http::Headers.new(env)
+    #   headers["Content-Type"] # => "text/plain"
     class Headers
       CGI_VARIABLES = %w(
         CONTENT_TYPE CONTENT_LENGTH
@@ -14,14 +19,16 @@ module ActionDispatch
       include Enumerable
       attr_reader :env
 
-      def initialize(env = {})
+      def initialize(env = {}) # :nodoc:
         @env = env
       end
 
+      # Returns the value for the given key mapped to @env.
       def [](key)
         @env[env_name(key)]
       end
 
+      # Sets the given value for the key mapped to @env.
       def []=(key, value)
         @env[env_name(key)] = value
       end
@@ -31,6 +38,13 @@ module ActionDispatch
       end
       alias :include? :key?
 
+      # Returns the value for the given key mapped to @env.
+      #
+      # If the key is not found and an optional code block is not provided,
+      # raises a <tt>KeyError</tt> exception.
+      #
+      # If the code block is provided, then it will be run and
+      # its result returned.
       def fetch(key, *args, &block)
         @env.fetch env_name(key), *args, &block
       end
@@ -39,12 +53,17 @@ module ActionDispatch
         @env.each(&block)
       end
 
+      # Returns a new Http::Headers instance containing the contents of
+      # <tt>headers_or_env</tt> and the original instance.
       def merge(headers_or_env)
         headers = Http::Headers.new(env.dup)
         headers.merge!(headers_or_env)
         headers
       end
 
+      # Adds the contents of <tt>headers_or_env</tt> to original instance
+      # entries; duplicate keys are overwritten with the values from
+      # <tt>headers_or_env</tt>.
       def merge!(headers_or_env)
         headers_or_env.each do |key, value|
           self[env_name(key)] = value
@@ -52,6 +71,8 @@ module ActionDispatch
       end
 
       private
+      # Converts a HTTP header name to an environment variable name if it is
+      # not contained within the headers hash.
       def env_name(key)
         key = key.to_s
         if key =~ HTTP_HEADER