Merge docrails

actionmailer/lib/action_mailer/base.rb

@@ -17,6 +17,7 @@ module ActionMailer #:nodoc:
   #  class Notifier < ActionMailer::Base
   #    def signup_notification(recipient)
   #      recipients recipient.email_address_with_name
+  #      bcc        ["bcc@example.com", "Order Watcher <watcher@example.com>"]
   #      from       "system@example.com"
   #      subject    "New account information"
   #      body       :account => recipient

actionpack/lib/action_view/helpers/date_helper.rb

@@ -111,7 +111,7 @@ def time_ago_in_words(from_time, include_seconds = false)
       #
       # ==== Options
       # * <tt>:use_month_numbers</tt> - Set to true if you want to use month numbers rather than month names (e.g.
-      #    "2" instead of "February").
+      #   "2" instead of "February").
       # * <tt>:use_short_month</tt>   - Set to true if you want to use the abbreviated month name instead of the full
       #   name (e.g. "Feb" instead of "February").
       # * <tt>:add_month_number</tt>  - Set to true if you want to show both, the month's number and name (e.g.

actionpack/lib/action_view/helpers/form_options_helper.rb

@@ -201,13 +201,21 @@ def options_for_select(container, selected = nil)
 
       # Returns a string of option tags that have been compiled by iterating over the +collection+ and assigning the
       # the result of a call to the +value_method+ as the option value and the +text_method+ as the option text.
-      # If +selected+ is specified, the element returning a match on +value_method+ will get the selected option tag.
+      # Example:
+      #   options_from_collection_for_select(@people, 'id', 'name')
+      # This will output the same HTML as if you did this:
+      #   <option value="#{person.id}">#{person.name}</option>
       #
-      # Example (call, result). Imagine a loop iterating over each +person+ in <tt>@project.people</tt> to generate an input tag:
-      #   options_from_collection_for_select(@project.people, "id", "name")
-      #     <option value="#{person.id}">#{person.name}</option>
+      # This is more often than not used inside a #select_tag like this example:
+      #   select_tag 'person', options_from_collection_for_select(@people, 'id', 'name')
       #
-      # NOTE: Only the option tags are returned, you have to wrap this call in a regular HTML select tag.
+      # If +selected+ is specified, the element returning a match on +value_method+ will get the selected option tag.
+      # Be sure to specify the same class as the +value_method+ when specifying a selected option.
+      # Failure to do this will produce undesired results. Example:
+      #   options_from_collection_for_select(@people, 'id', 'name', '1')
+      # Will not select a person with the id of 1 because 1 (an Integer) is not the same as '1' (a string)
+      #   options_from_collection_for_select(@people, 'id', 'name', 1)
+      # should produce the desired results.
       def options_from_collection_for_select(collection, value_method, text_method, selected = nil)
         options = collection.map do |element|
           [element.send(text_method), element.send(value_method)]

activerecord/lib/active_record/associations.rb

@@ -153,7 +153,7 @@ def clear_association_cache #:nodoc:
     #   #others.destroy_all               |   X   |    X     |    X
     #   #others.find(*args)               |   X   |    X     |    X
     #   #others.find_first                |   X   |          |
-    #   #others.exist?                    |   X   |    X     |    X
+    #   #others.exists?                   |   X   |    X     |    X
     #   #others.uniq                      |   X   |    X     |    X
     #   #others.reset                     |   X   |    X     |    X
     #
@@ -652,7 +652,7 @@ module ClassMethods
       #   Returns the number of associated objects.
       # [collection.find(...)]
       #   Finds an associated object according to the same rules as ActiveRecord::Base.find.
-      # [collection.exist?(...)]
+      # [collection.exists?(...)]
       #   Checks whether an associated object with the given conditions exists.
       #   Uses the same rules as ActiveRecord::Base.exists?.
       # [collection.build(attributes = {}, ...)]
@@ -682,7 +682,7 @@ module ClassMethods
       # * <tt>Firm#clients.empty?</tt> (similar to <tt>firm.clients.size == 0</tt>)
       # * <tt>Firm#clients.size</tt> (similar to <tt>Client.count "firm_id = #{id}"</tt>)
       # * <tt>Firm#clients.find</tt> (similar to <tt>Client.find(id, :conditions => "firm_id = #{id}")</tt>)
-      # * <tt>Firm#clients.exist?(:name => 'ACME')</tt> (similar to <tt>Client.exist?(:name => 'ACME', :firm_id => firm.id)</tt>)
+      # * <tt>Firm#clients.exists?(:name => 'ACME')</tt> (similar to <tt>Client.exists?(:name => 'ACME', :firm_id => firm.id)</tt>)
       # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new("firm_id" => id)</tt>)
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save; c</tt>)
       # The declaration can also include an options hash to specialize the behavior of the association.
@@ -1107,7 +1107,7 @@ def belongs_to(association_id, options = {})
       #   Finds an associated object responding to the +id+ and that
       #   meets the condition that it has to be associated with this object.
       #   Uses the same rules as ActiveRecord::Base.find.
-      # [collection.exist?(...)]
+      # [collection.exists?(...)]
       #   Checks whether an associated object with the given conditions exists.
       #   Uses the same rules as ActiveRecord::Base.exists?.
       # [collection.build(attributes = {})]
@@ -1133,7 +1133,7 @@ def belongs_to(association_id, options = {})
       # * <tt>Developer#projects.empty?</tt>
       # * <tt>Developer#projects.size</tt>
       # * <tt>Developer#projects.find(id)</tt>
-      # * <tt>Developer#clients.exist?(...)</tt>
+      # * <tt>Developer#clients.exists?(...)</tt>
       # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new("project_id" => id)</tt>)
       # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new("project_id" => id); c.save; c</tt>)
       # The declaration may include an options hash to specialize the behavior of the association.

activerecord/lib/active_record/base.rb

@@ -811,8 +811,7 @@ def destroy(id)
       #
       # ==== Parameters
       #
-      # * +updates+ - A string of column and value pairs that will be set on any records that match conditions.
-      #               What goes into the SET clause.
+      # * +updates+ - A string of column and value pairs that will be set on any records that match conditions. This creates the SET clause of the generated SQL.
       # * +conditions+ - An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro for more info.
       # * +options+ - Additional options are <tt>:limit</tt> and <tt>:order</tt>, see the examples for usage.
       #

activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb

@@ -123,6 +123,7 @@ def retrieve_connection
         connection_handler.retrieve_connection(self)
       end
 
+      # Returns true if +ActiveRecord+ is connected.
       def connected?
         connection_handler.connected?(self)
       end

activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb

@@ -32,10 +32,12 @@ def initialize(name, default, sql_type = nil, null = true)
         @primary = nil
       end
 
+      # Returns +true+ if the column is either of type string or text.
       def text?
         type == :string || type == :text
       end
 
+      # Returns +true+ if the column is either of type integer, float or decimal.
       def number?
         type == :integer || type == :float || type == :decimal
       end
@@ -295,7 +297,7 @@ def add_column_options!(sql, options)
     #         puts t.class  # => "ActiveRecord::ConnectionAdapters::TableDefinition"
     #       end
     #     end
-    #     
+    #
     #     def self.down
     #       ...
     #     end

activerecord/lib/active_record/validations.rb

@@ -1049,15 +1049,15 @@ def errors
 
     protected
       # Overwrite this method for validation checks on all saves and use <tt>Errors.add(field, msg)</tt> for invalid attributes.
-      def validate #:doc:
+      def validate
       end
 
       # Overwrite this method for validation checks used only on creation.
-      def validate_on_create #:doc:
+      def validate_on_create
       end
 
       # Overwrite this method for validation checks used only on updates.
-      def validate_on_update # :doc:
+      def validate_on_update
       end
   end
 end