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

6 files changed, 49 insertions, 11 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
diff --git a/activerecord/README.rdoc b/activerecord/README.rdoc
index e04abe9b37..335f0e083f 100644
--- a/activerecord/README.rdoc
+++ b/activerecord/README.rdoc
@@ -19,9 +19,11 @@ A short rundown of some of the major features:
 
    class Product < ActiveRecord::Base
    end
-
-   The Product class is automatically mapped to the table named "products",
-   which might look like this:
+  
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+  
+The Product class is automatically mapped to the table named "products",
+which might look like this:
 
    CREATE TABLE products (
      id int(11) NOT NULL auto_increment,
@@ -29,11 +31,9 @@ A short rundown of some of the major features:
      PRIMARY KEY  (id)
    );
 
-   This would also define the following accessors: `Product#name` and
-   `Product#name=(new_name)`
-
-  {Learn more}[link:classes/ActiveRecord/Base.html]
-
+This would also define the following accessors: `Product#name` and
+`Product#name=(new_name)`.
+  
 
 * Associations between objects defined by simple class methods.
 
diff --git a/activerecord/lib/active_record/attribute_assignment.rb b/activerecord/lib/active_record/attribute_assignment.rb
index 30fa2c8ba5..87ecbe54f1 100644
--- a/activerecord/lib/active_record/attribute_assignment.rb
+++ b/activerecord/lib/active_record/attribute_assignment.rb
@@ -11,6 +11,15 @@ module ActiveRecord
     # If the passed hash responds to <tt>permitted?</tt> method and the return value
     # of this method is +false+ an <tt>ActiveModel::ForbiddenAttributesError</tt>
     # exception is raised.
+    #
+    #   cat = Cat.new(name: "Gorby", status: "yawning")
+    #   cat.attributes # =>  { "name" => "Gorby", "status" => "yawning" }
+    #   cat.assign_attributes(status: "sleeping")
+    #   cat.attributes # =>  { "name" => "Gorby", "status" => "sleeping" }
+    #
+    # New attributes will be persisted in the database when the object is saved.
+    #
+    # Aliased to <tt>attributes=</tt>.
     def assign_attributes(new_attributes)
       if !new_attributes.respond_to?(:stringify_keys)
         raise ArgumentError, "When assigning attributes, you must pass a hash as an argument."
diff --git a/activerecord/lib/active_record/connection_adapters/column.rb b/activerecord/lib/active_record/connection_adapters/column.rb
index 187eefb9e4..38efebeaf3 100644
--- a/activerecord/lib/active_record/connection_adapters/column.rb
+++ b/activerecord/lib/active_record/connection_adapters/column.rb
@@ -72,6 +72,8 @@ module ActiveRecord
       end
 
       # Casts a Ruby value to something appropriate for writing to the database.
+      # Numeric columns will typecast boolean and string to appropriate numeric
+      # values.
       def type_cast_for_write(value)
         return value unless number?
 
diff --git a/activerecord/lib/active_record/connection_adapters/postgresql/column.rb b/activerecord/lib/active_record/connection_adapters/postgresql/column.rb
index 2cbcd5fd50..1d22b56964 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql/column.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql/column.rb
@@ -98,6 +98,9 @@ module ActiveRecord
         end
       end
 
+      # Casts a Ruby value to something appropriate for writing to PostgreSQL.
+      # see ActiveRecord::ConnectionAdapters::Class#type_cast_for_write
+      # see ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::OID::Type
       def type_cast_for_write(value)
         if @oid_type.respond_to?(:type_cast_for_write)
           @oid_type.type_cast_for_write(value)
diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb
index c25c97cfa8..f2a2f3c3db 100644
--- a/activesupport/lib/active_support/time_with_zone.rb
+++ b/activesupport/lib/active_support/time_with_zone.rb
@@ -185,8 +185,11 @@ module ActiveSupport
     end
     alias_method :rfc822, :rfc2822
 
-    # <tt>:db</tt> format outputs time in UTC; all others output time in local.
-    # Uses TimeWithZone's +strftime+, so <tt>%Z</tt> and <tt>%z</tt> work correctly.
+    # Returns a string of the object's date and time.
+    # Accepts an optional <tt>format</tt>:
+    # * <tt>:default</tt> - default value, mimics Ruby 1.9 Time#to_s format.
+    # * <tt>:db</tt> - format outputs time in UTC :db time. See Time#to_formatted_s(:db).
+    # * Any key in <tt>Time::DATE_FORMATS</tt> can be used. See active_support/core_ext/time/conversions.rb.
     def to_s(format = :default)
       if format == :db
         utc.to_s(format)